Loading...
Searching...
No Matches
SamFileHeader Class Reference

This class allows a user to get/set the fields in a SAM/BAM Header. More...

`#include <SamFileHeader.h>`

Collaboration diagram for SamFileHeader:
[legend]

## Public Member Functions

Copying a Header
These methods are ways of copying the contents of one header into another one.
| SamFileHeader (const SamFileHeader &header)
| Copy Constructor copies the specified header into this one.
SamFileHeader & | operator= (const SamFileHeader &header)
| Overload operator = to copy the passed in header into this header.
bool | copy (const SamFileHeader &header)
| Copy method copies the passed in header into this header.
void | resetHeader ()
| Initialize the header.
Get the Entire Header
Get the entire header as a single string.
bool | getHeaderString (std::string &header) const
| Set the passed in string to the entire header string, clearing its current contents.
int | getReferenceID (const String &referenceName, bool addID=false)
| Get the reference ID for the specified reference name (chromosome).
int | getReferenceID (const char *referenceName, bool addID=false)
| Get the reference ID for the specified reference name (chromosome).
const String & | getReferenceLabel (int id) const
| Return the reference name (chromosome) for the specified reference id.
const SamReferenceInfo & | getReferenceInfo () const
| Get the Reference Information.
SamReferenceInfo & | getReferenceInfoForBamInterface ()
Adding an entire header/comment line.
These methods are ways of adding an entire header line at once.
bool | addHeaderLine (const char *type, const char *tag, const char *value)
| Add a header line that is just one tag with a const char* value.
bool | addHeaderLine (const char *headerLine)
| Add a header line that is already preformatted in a const char*.
bool | addHeader (const char *header)
| Add a header that is already preformatted in a const char*.
bool | addComment (const char *comment)
| Add the specified comment to the header (do not include "@CO" or "\n").
Set/Add/Remove a Single Tag
The passed in tag should be the two character SAM tag as defined in the SAM spec. A tag is removed from the header record by setting it to "". For the SQ and RG header types, the key tags (SN for SQ and ID for RG) may not be modified or removed once set. This is because these values are used as a lookup key for the header record, so the entire record must be removed.
bool | setHDTag (const char *tag, const char *value)
| Set the specified tag to the specified value in the HD header, remove the tag by specifying value="".
bool | setSQTag (const char *tag, const char *value, const char *name)
| Set the specified tag to the specified value in the SQ header with the specified name, remove the tag by specifying value="".
bool | setRGTag (const char *tag, const char *value, const char *id)
| Set the specified tag to the specified value in the RG header with the specified id, remove the tag by specifying value="".
bool | setPGTag (const char *tag, const char *value, const char *id)
| Set the specified tag to the specified value in the PG header with the specified id, remove the tag by specifying value="".
Add an Already Setup SamHeaderRecord
NOTE: These methods add a pointer to the passed in record. The header record will be deleted when it's cleaned up from this header. NOTE: Do NOT delete the passed in record, the SamFileHeader class takes care of that itself.
bool | addHD (SamHeaderHD *hd)
| Add the HD record to the header.
bool | addSQ (SamHeaderSQ *sq)
| Add the SQ record to the header.
bool | addRG (SamHeaderRG *rg)
| Add the RG record to the header.
bool | addPG (SamHeaderPG *pg)
| Add the PG record to the header.
bool | addRecordCopy (const SamHeaderRecord &hdrRec)
| Add a copy of the specified header record to the header.
Remove an Entire Header Record
bool | removeHD ()
| Remove the HD record.
bool | removeSQ (const char *name)
| Remove SQ record with the specified key.
bool | removeRG (const char *id)
| Remove RG record with the specified key.
bool | removePG (const char *id)
| Remove PG record with the specified key.
Get a Specific Tag
These methods return the value associated with the specified tag. If the tag does not exist in the record "" is returned. For SQ, RG, and PG the value returned is for the tag associated with the specified key (name/id). If a record with that key does not exist or if the tag does not exist for the record with that key, "" is returned.
const char * | getHDTagValue (const char *tag)
| Returns the value associated with the specified HD tag, returning "" if the tag does not exist in the header.
const char * | getSQTagValue (const char *tag, const char *name)
| Get the value associated with the specified tag on the SQ line with the specified sequence name, returning "" if the tag or key does not exist.
const char * | getRGTagValue (const char *tag, const char *id)
| Get the value associated with the specified tag on the RG line with the specified read group identifier, returning "" if the tag or key does not exist.
const char * | getPGTagValue (const char *tag, const char *id)
| Get the value associated with the specified tag on the RG line with the specified id, returning "" if the tag or key does not exist.
int | getNumSQs ()
| Get the number of SQ objects.
int | getNumRGs ()
| Get the number of RG objects.
int | getNumPGs ()
| Get the number of PG objects.
Get a Specific Header Record
These methods return a reference to the specific record that was requested, returning NULL if that record does not exist in the header. The returned record can be modified to add/remove some tags. Since a reference is returned, the SamHeaderFile automatically reflects these changes.
SamHeaderHD * | getHD ()
| Get the HD object, returning NULL if there is no HD record.
SamHeaderSQ * | getSQ (const char *name)
| Get the SQ object with the specified sequence name, returning NULL if there is no SQ object with that key.
SamHeaderRG * | getRG (const char *id)
| Get the RG object with the specified read group identifier, returning NULL if there is no RG object with that key.
SamHeaderPG * | getPG (const char *id)
| Get the PG object with the specified id, returning NULL if there is no PG object with that key.
const char * | getSortOrder ()
| Return the Sort Order value that is set in the Header, returning "" if this field does not exist.
const char * | getTagSO ()
| DEPRECATED.

## Get the Header Record/Comment/Line by Record/Comment/Line

These methods iterate through the header. NOTE: both getNextHeaderRecord and getNextHeaderLine increment the same iterator. getNextHeaderRecord that takes a header type uses the same iterator as the getNextXXRecord with that type. Otherwise the iterators are independent.
static const std::string | EMPTY_RETURN = ""
SamHeaderRecord * | getNextSQRecord ()
| Get the next SQ header record.
SamHeaderRecord * | getNextRGRecord ()
| Get the next RG header record.
SamHeaderRecord * | getNextPGRecord ()
| Get the next PG header record.
void | resetSQRecordIter ()
| Reset to the beginning of the header records so the next call to getNextSQRecord returns the first SQ header record.
void | resetRGRecordIter ()
| Reset to the beginning of the header records so the next call to getNextRGRecord returns the first RG header record.
void | resetPGRecordIter ()
| Reset to the beginning of the header records so the next call to getNextPGRecord returns the first PG header record.
SamHeaderRecord * | getNextHeaderRecord (uint32_t &index, SamHeaderRecord::SamHeaderRecordType headerType)
| Get the next header record of the specified type starting from the specified index and update the index.
SamHeaderRecord * | getNextHeaderRecord ()
| Get the next header record, but not comment line.
bool | getNextHeaderLine (std::string &headerLine)
| Set the passed in string to the next header line, overwritting the passed in string.
void | resetHeaderRecordIter ()
| Reset to the beginning of the header records so the next call to getNextHeaderRecord returns the first header line.
void | appendCommentLines (std::string &commentLines)
| Append all of the comment lines to the specified string.
const char * | getNextComment ()
| Returns the comment on the next comment line.
void | resetCommentIter ()
| Resets to the beginning of the comments so getNextComment returns the first comment.
const char * | getErrorMessage ()
| Get the failure message if a method returned failure.

## Detailed Description

This class allows a user to get/set the fields in a SAM/BAM Header.

Sam/Bam headers contain comments and multiple SamHeaderRecords (HD, SQs, RGs, PGs) comprised of tag/value pairs with each tag only appearing once within a specific record.

Definition at line 34 of file SamFileHeader.h.

## Constructor & Destructor Documentation

## SamFileHeader() [1/2]

SamFileHeader::SamFileHeader | ( |  | ) |

Definition at line 25 of file SamFileHeader.cpp.

: myHD(NULL),
myReferenceInfo(),
myErrorMessage("")
{
resetHeader();
mySQs.setCaseSensitive(true);
myRGs.setCaseSensitive(true);
myPGs.setCaseSensitive(true);
}
SamFileHeader::resetHeader
void resetHeader()
Initialize the header.
Definition SamFileHeader.cpp:90

## ~SamFileHeader()

SamFileHeader::~SamFileHeader | ( |  | ) |

Definition at line 38 of file SamFileHeader.cpp.

{
resetHeader();
}

## SamFileHeader() [2/2]

SamFileHeader::SamFileHeader | ( | const SamFileHeader & | header | ) |

Copy Constructor copies the specified header into this one.

Definition at line 45 of file SamFileHeader.cpp.

{
copy(header);
}
SamFileHeader::copy
bool copy(const SamFileHeader &header)
Copy method copies the passed in header into this header.
Definition SamFileHeader.cpp:59

References copy().

## Member Function Documentation

## addComment()

bool SamFileHeader::addComment | ( | const char * | comment | ) |

Add the specified comment to the header (do not include "@CO" or "\n").

Returns
  true if successfully added, false if not.

Definition at line 213 of file SamFileHeader.cpp.

{
if((comment != NULL) && (strcmp(comment, EMPTY_RETURN.c_str()) != 0))
{
// Valid comment, so add it.
myComments.push_back(comment);
}
return(true);
}

## addHD()

bool SamFileHeader::addHD | ( | SamHeaderHD * | hd | ) |

Add the HD record to the header.

Note: it adds a pointer to the passed in header record. The header record will be deleted when it is cleaned up from this header.

Returns
  true if the record was successfully added, false otherwise.

Definition at line 393 of file SamFileHeader.cpp.

{
// If there is already an HD header or if null
// was passed in, return false.
if(myHD != NULL)
{
myErrorMessage = "Failed add an HD tag - there is already one";
return(false);
}
if(hd == NULL)
{
myErrorMessage = "Failed add an HD tag - no tag specified";
return(false);
}
myHD = hd;
myHeaderRecords.push_back(myHD);
return(true);
}

Referenced by addRecordCopy().

## addHeader()

bool SamFileHeader::addHeader | ( | const char * | header | ) |

Add a header that is already preformatted in a const char*.

Returns true if at least one header line was successfully added.

Definition at line 204 of file SamFileHeader.cpp.

{
// Parse the added header line.
String headerString = header;
return(parseHeader(headerString));
}
String
Definition StringBasics.h:39

## addHeaderLine() [1/2]

bool SamFileHeader::addHeaderLine | ( | const char * | headerLine | ) |

Add a header line that is already preformatted in a const char*.

Returns true if at least one header line was successfully added.

Definition at line 195 of file SamFileHeader.cpp.

{
// Parse the added header line.
String headerString = headerLine;
return(parseHeader(headerString));
}

## addHeaderLine() [2/2]

bool SamFileHeader::addHeaderLine | ( | const char * | type,
|  | const char * | tag,
|  | const char * | value
| ) |  |

Add a header line that is just one tag with a const char* value.

Note: This method will only do one tag per type on a line, so if a type has multiple tags, the whole line needs to be added at once, and a different method should be used.

Definition at line 180 of file SamFileHeader.cpp.

{
String headerLine;
headerLine += "@";
headerLine += type;
headerLine += "\t";
headerLine += tag;
headerLine += ":";
headerLine += value;
return(addHeaderLine(headerLine.c_str()));
}
SamFileHeader::addHeaderLine
bool addHeaderLine(const char *type, const char *tag, const char *value)
Add a header line that is just one tag with a const char* value.
Definition SamFileHeader.cpp:180

References addHeaderLine().

Referenced by addHeaderLine().

## addPG()

bool SamFileHeader::addPG | ( | SamHeaderPG * | pg | ) |

Add the PG record to the header.

Note: it adds a pointer to the passed in header record. The header record will be deleted when it is cleaned up from this header.

Returns
  true if the record was successfully added, false otherwise.

Definition at line 492 of file SamFileHeader.cpp.

{
// If a null pointer was passed in, return false.
if(pg == NULL)
{
myErrorMessage = "SAM/BAM Header line failed to allocate PG.";
return(false);
}
const char* id = pg->getTagValue("ID");
if(strcmp(id, EMPTY_RETURN.c_str()) == 0)
{
// ID is not set, so can't add the header record.
myErrorMessage = "SAM/BAM Header line failure: Skipping PG line that is missing the ID field.";
return(false);
}
// Determine whether or not a record with this
// key is already in the hash.
if(myPGs.Find(id) < 0)
{
// It is not already in the hash so
// add it.
myPGs.Add(id, pg);
myHeaderRecords.push_back(pg);
return(true);
}
// It is already in the hash, so cannot be added.
myErrorMessage = "SAM/BAM Header line failure: Skipping PG line that has a repeated ID field.";
return(false);
}
SamHeaderRecord::getTagValue
const char * getTagValue(const char *tag) const
Return the value associated with the specified tag.
Definition SamHeaderRecord.cpp:100

References SamHeaderRecord::getTagValue().

Referenced by addRecordCopy().

## addRecordCopy()

bool SamFileHeader::addRecordCopy | ( | const SamHeaderRecord & | hdrRec | ) |

Add a copy of the specified header record to the header.

Note: it creates a new header record that is identical to the specified one and adds it to the header. The passed in pointer will not be deleted due to this.

Returns
  true if the record was successfully added, false otherwise.

Definition at line 526 of file SamFileHeader.cpp.

{
SamHeaderRecord* newRec = hdrRec.createCopy();
bool returnVal = true;
switch(newRec->getType())
{
case SamHeaderRecord::HD:
returnVal = addHD((SamHeaderHD*)newRec);
break;
case SamHeaderRecord::PG:
returnVal = addPG((SamHeaderPG*)newRec);
break;
case SamHeaderRecord::RG:
returnVal = addRG((SamHeaderRG*)newRec);
break;
case SamHeaderRecord::SQ:
returnVal = addSQ((SamHeaderSQ*)newRec);
break;
default:
myErrorMessage = "Failed to copy a header record, unknown type.";
returnVal = false;
break;
}
return(returnVal);
}
SamFileHeader::addPG
bool addPG(SamHeaderPG *pg)
Add the PG record to the header.
Definition SamFileHeader.cpp:492
SamFileHeader::addRG
bool addRG(SamHeaderRG *rg)
Add the RG record to the header.
Definition SamFileHeader.cpp:458
SamFileHeader::addSQ
bool addSQ(SamHeaderSQ *sq)
Add the SQ record to the header.
Definition SamFileHeader.cpp:415
SamFileHeader::addHD
bool addHD(SamHeaderHD *hd)
Add the HD record to the header.
Definition SamFileHeader.cpp:393
SamHeaderHD
Definition SamHeaderHD.h:24
SamHeaderPG
Definition SamHeaderPG.h:25
SamHeaderRG
Definition SamHeaderRG.h:24
SamHeaderRecord
This class encapsulates the tag value pairs contained with a SAM Header line with accessors for getti...
Definition SamHeaderRecord.h:28
SamHeaderRecord::getType
SamHeaderRecordType getType()
Return the type of this header record (HD, SQ, RG, or PG) as an enum.
Definition SamHeaderRecord.cpp:315
SamHeaderRecord::createCopy
virtual SamHeaderRecord * createCopy() const =0
Return a pointer to a newly created header record of the appropriate type that is a copy of this reco...
SamHeaderRecord::HD
@ HD
Header.
Definition SamHeaderRecord.h:32
SamHeaderRecord::SQ
@ SQ
Sequence Dictionary.
Definition SamHeaderRecord.h:33
SamHeaderRecord::PG
@ PG
Program.
Definition SamHeaderRecord.h:35
SamHeaderRecord::RG
@ RG
Read Group.
Definition SamHeaderRecord.h:34
SamHeaderSQ
Definition SamHeaderSQ.h:24

References addHD(), addPG(), addRG(), addSQ(), SamHeaderRecord::createCopy(), SamHeaderRecord::getType(), SamHeaderRecord::HD, SamHeaderRecord::PG, SamHeaderRecord::RG, and SamHeaderRecord::SQ.

## addRG()

bool SamFileHeader::addRG | ( | SamHeaderRG * | rg | ) |

Add the RG record to the header.

Note: it adds a pointer to the passed in header record. The header record will be deleted when it is cleaned up from this header.

Returns
  true if the record was successfully added, false otherwise.

Definition at line 458 of file SamFileHeader.cpp.

{
if(rg == NULL)
{
// null pointer passed in, can't add it.
myErrorMessage = "SAM/BAM Header line failed to allocate RG.";
return(false);
}
const char* id = rg->getTagValue("ID");
if(strcmp(id, EMPTY_RETURN.c_str()) == 0)
{
// ID is not set, so can't add it.
myErrorMessage = "SAM/BAM Header line failure: Skipping RG line that is missing the ID field.";
return(false);
}
// Determine whether or not a record with this
// key is already in the hash.
if(myRGs.Find(id) < 0)
{
// It is not already in the hash so
// add it.
myRGs.Add(id, rg);
myHeaderRecords.push_back(rg);
return(true);
}
// It is already in the hash, so cannot be added.
myErrorMessage = "SAM/BAM Header line failure: Skipping RG line that has a repeated ID field.";
return(false);
}

References SamHeaderRecord::getTagValue().

Referenced by addRecordCopy().

## addSQ()

bool SamFileHeader::addSQ | ( | SamHeaderSQ * | sq | ) |

Add the SQ record to the header.

Note: it adds a pointer to the passed in header record. The header record will be deleted when it is cleaned up from this header.

Returns
  true if the record was successfully added, false otherwise.

Definition at line 415 of file SamFileHeader.cpp.

{
if(sq == NULL)
{
// null pointer passed in, can't add it.
myErrorMessage = "SAM/BAM Header line failed to allocate SQ.";
return(false);
}
const char* name = sq->getTagValue("SN");
const char* length = sq->getTagValue("LN");
if(strcmp(name, EMPTY_RETURN.c_str()) == 0)
{
// SN is not set, so can't add it.
myErrorMessage =
"SAM/BAM Header line failure: Skipping SQ line that is missing the SN field.";
return(false);
}
if(strcmp(length, EMPTY_RETURN.c_str()) == 0)
{
// LN is not set, so can't add it.
myErrorMessage =
"SAM/BAM Header line failure: Skipping SQ line that is missing the LN field.";
return(false);
}
// Determine whether or not a record with this
// key is already in the hash.
if(mySQs.Find(name) < 0)
{
// It is not already in the hash so add it.
mySQs.Add(name, sq);
myHeaderRecords.push_back(sq);
myReferenceInfo.add(name, atoi(length));
return(true);
}
// It is already in the hash, so cannot be added.
myErrorMessage = "SAM/BAM Header line failure: Skipping SQ line that has a repeated SN field.";
return(false);
}
SamReferenceInfo::add
void add(const char *referenceSequenceName, int32_t referenceSequenceLength)
Add reference sequence name and reference sequence length.
Definition SamReferenceInfo.cpp:35

References SamReferenceInfo::add(), and SamHeaderRecord::getTagValue().

Referenced by addRecordCopy().

## appendCommentLines()

void SamFileHeader::appendCommentLines | ( | std::string & | commentLines | ) |

Append all of the comment lines to the specified string.

Definition at line 972 of file SamFileHeader.cpp.

{
for(unsigned int i = 0; i < myComments.size(); i++)
{
commentLines += "@CO\t";;
commentLines += myComments[i];
commentLines += "\n";
}
}

## copy()

bool SamFileHeader::copy | ( | const SamFileHeader & | header | ) |

Copy method copies the passed in header into this header.

Returns true if at least one header line was successfully copied.

Definition at line 59 of file SamFileHeader.cpp.

{
// Check to see if the passed in value is the same as this.
if(this == &header)
{
return(true);
}
resetHeader();
// Copy the records by getting the other header's header string
// and parsing it.
std::string newString;
bool status = header.getHeaderString(newString);
String newHeaderString = newString.c_str();
status &= parseHeader(newHeaderString);
myCurrentHeaderIndex = header.myCurrentHeaderIndex;
myCurrentCommentIndex = header.myCurrentCommentIndex;
// Clear the reference info and copy it to ensure it is the same.
myReferenceInfo.clear();
// Copy Reference contigs, hash, lengths.
myReferenceInfo = header.myReferenceInfo;
return(status);
}
SamFileHeader::getHeaderString
bool getHeaderString(std::string &header) const
Set the passed in string to the entire header string, clearing its current contents.
Definition SamFileHeader.cpp:131
SamReferenceInfo::clear
void clear()
Reset this reference info.
Definition SamReferenceInfo.cpp:123

References SamReferenceInfo::clear(), getHeaderString(), and resetHeader().

Referenced by SamFileHeader(), and operator=().

## getErrorMessage()

const char * SamFileHeader::getErrorMessage | ( |  | ) |

inline

Get the failure message if a method returned failure.

Definition at line 423 of file SamFileHeader.h.

{ return(myErrorMessage.c_str()); }

## getHD()

SamHeaderHD * SamFileHeader::getHD | ( |  | ) |

Get the HD object, returning NULL if there is no HD record.

Definition at line 768 of file SamFileHeader.cpp.

{
return(myHD);
}

## getHDTagValue()

const char * SamFileHeader::getHDTagValue | ( | const char * | tag | ) |

Returns the value associated with the specified HD tag, returning "" if the tag does not exist in the header.

Definition at line 683 of file SamFileHeader.cpp.

{
if(myHD == NULL)
{
// return blank since there is no HD type.
return(EMPTY_RETURN.c_str());
}
return(myHD->getTagValue(tag));
}

References SamHeaderRecord::getTagValue().

## getHeaderString()

bool SamFileHeader::getHeaderString | ( | std::string & | header | ) | const

Set the passed in string to the entire header string, clearing its current contents.

Returns
  true if successfully set (even if set to "")

Definition at line 131 of file SamFileHeader.cpp.

{
header.clear();
// Keep getting header lines until there are no more - false returned.
unsigned int index = 0;
while(getHeaderLine(index, header) != false)
{
++index;
}
return(true);
}

Referenced by copy().

## getNextComment()

const char * SamFileHeader::getNextComment | ( |  | ) |

Returns the comment on the next comment line.

Returns "" if all comment lines have been returned, until resetCommentIter is called.

Definition at line 985 of file SamFileHeader.cpp.

{
if(myCurrentCommentIndex < myComments.size())
{
return(myComments[myCurrentCommentIndex++].c_str());
}
// Already gone through all the comments, return EMPTY_RETURN.c_str().
return(EMPTY_RETURN.c_str());
}

## getNextHeaderLine()

bool SamFileHeader::getNextHeaderLine | ( | std::string & | headerLine | ) |

Set the passed in string to the next header line, overwritting the passed in string.

If there are no more header lines or there is an error, false is returned and the passed in string is set to "" until a rest is called. NOTE: both getNextHeaderRecord and getNextHeaderLine increment the same iterator.

Definition at line 941 of file SamFileHeader.cpp.

{
headerLine = EMPTY_RETURN.c_str();
// Until the header is set, keep reading.
// Header could return EMPTY_RETURN.c_str() if the header line is blank.
while(headerLine == EMPTY_RETURN.c_str())
{
if(getHeaderLine(myCurrentHeaderIndex, headerLine) == false)
{
// getHeaderLine failed, so stop processing, and return false.
return(false);
}
else
{
// In range, increment the index.
++myCurrentHeaderIndex;
}
}
return(true);
}

## getNextHeaderRecord() [1/2]

SamHeaderRecord * SamFileHeader::getNextHeaderRecord | ( |  | ) |

Get the next header record, but not comment line.

After all headers have been retrieved, NULL is returned until a reset is called. NOTE: both getNextHeaderRecord and getNextHeaderLine increment the same iterator.

Definition at line 908 of file SamFileHeader.cpp.

{
// Get the next header record
SamHeaderRecord* foundRecord = NULL;
// Loop until a record is found or until out of range of the
// headerRecord vector.
while((myCurrentHeaderIndex < myHeaderRecords.size())
&& (foundRecord == NULL))
{
// Get the next record.
foundRecord = myHeaderRecords[myCurrentHeaderIndex];
// Either way, increment the index.
++myCurrentHeaderIndex;
// Check to see if the next record is active.
if(!foundRecord->isActiveHeaderRecord())
{
// Not active, so clear the pointer.
foundRecord = NULL;
}
}
// Return the record if it was found. Will be null if none were found.
return(foundRecord);
}
SamHeaderRecord::isActiveHeaderRecord
bool isActiveHeaderRecord()
This record is active (true) if there is at least one tag set.
Definition SamHeaderRecord.cpp:301

References SamHeaderRecord::isActiveHeaderRecord().

Referenced by getNextPGRecord(), getNextRGRecord(), and getNextSQRecord().

## getNextHeaderRecord() [2/2]

SamHeaderRecord * SamFileHeader::getNextHeaderRecord | ( | uint32_t & | index,
|  | SamHeaderRecord::SamHeaderRecordType | headerType
| ) |  |

Get the next header record of the specified type starting from the specified index and update the index.

After all headers of that type have been retrieved, NULL is returned until a reset is called for that type.

Definition at line 871 of file SamFileHeader.cpp.

{
SamHeaderRecord* foundRecord = NULL;
// Loop until a record is found or until out of range of the
// headerRecord vector.
while((index < myHeaderRecords.size())
&& (foundRecord == NULL))
{
// Get the next record.
foundRecord = myHeaderRecords[index];
// Either way, increment the index.
++index;
// Check to see if the next record is active.
if(!foundRecord->isActiveHeaderRecord())
{
// Not active, so clear the pointer.
foundRecord = NULL;
}
// Check to see if the record is the right type.
else if(foundRecord->getType() != headerType)
{
// Not the right type, so clear the pointer.
foundRecord = NULL;
}
}
// Return the record if it was found. Will be null if none were found.
return(foundRecord);
}

References SamHeaderRecord::getType(), and SamHeaderRecord::isActiveHeaderRecord().

## getNextPGRecord()

SamHeaderRecord * SamFileHeader::getNextPGRecord | ( |  | ) |

Get the next PG header record.

After all PG headers have been retrieved, NULL is returned until a reset is called. Independent from getNextHeaderRecord, getNextHeaderLine and the other getNextXXRecord methods and the associated reset methods.

Definition at line 835 of file SamFileHeader.cpp.

{
return(getNextHeaderRecord(myCurrentPGIndex,
SamHeaderRecord::PG));
}
SamFileHeader::getNextHeaderRecord
SamHeaderRecord * getNextHeaderRecord()
Get the next header record, but not comment line.
Definition SamFileHeader.cpp:908

References getNextHeaderRecord(), and SamHeaderRecord::PG.

## getNextRGRecord()

SamHeaderRecord * SamFileHeader::getNextRGRecord | ( |  | ) |

Get the next RG header record.

After all RG headers have been retrieved, NULL is returned until a reset is called. Independent from getNextHeaderRecord, getNextHeaderLine and the other getNextXXRecord methods and the associated reset methods.

Definition at line 826 of file SamFileHeader.cpp.

{
return(getNextHeaderRecord(myCurrentRGIndex,
SamHeaderRecord::RG));
}

References getNextHeaderRecord(), and SamHeaderRecord::RG.

## getNextSQRecord()

SamHeaderRecord * SamFileHeader::getNextSQRecord | ( |  | ) |

Get the next SQ header record.

After all SQ headers have been retrieved, NULL is returned until a reset is called. Independent from getNextHeaderRecord, getNextHeaderLine and the other getNextXXRecord methods and the associated reset methods.

Definition at line 817 of file SamFileHeader.cpp.

{
return(getNextHeaderRecord(myCurrentSQIndex,
SamHeaderRecord::SQ));
}

References getNextHeaderRecord(), and SamHeaderRecord::SQ.

## getNumPGs()

int SamFileHeader::getNumPGs | ( |  | ) |

Get the number of PG objects.

Definition at line 761 of file SamFileHeader.cpp.

{
return(myPGs.Entries());
}

## getNumRGs()

int SamFileHeader::getNumRGs | ( |  | ) |

Get the number of RG objects.

Definition at line 754 of file SamFileHeader.cpp.

{
return(myRGs.Entries());
}

## getNumSQs()

int SamFileHeader::getNumSQs | ( |  | ) |

Get the number of SQ objects.

Definition at line 747 of file SamFileHeader.cpp.

{
return(mySQs.Entries());
}

Referenced by SamValidator::isValidRname().

## getPG()

SamHeaderPG * SamFileHeader::getPG | ( | const char * | id | ) |

Get the PG object with the specified id, returning NULL if there is no PG object with that key.

Definition at line 789 of file SamFileHeader.cpp.

{
return((SamHeaderPG*)(myPGs.Object(id)));
}

Referenced by setPGTag().

## getPGTagValue()

const char * SamFileHeader::getPGTagValue | ( | const char * | tag,
|  | const char * | id
| ) |  |

Get the value associated with the specified tag on the RG line with the specified id, returning "" if the tag or key does not exist.

Definition at line 730 of file SamFileHeader.cpp.

{
// Look up the id in the hash to get the associated PG object.
SamHeaderPG* pg = (SamHeaderPG*)(myPGs.Object(id));
// If it is NULL - the tag was not found, so return
if(pg == NULL)
{
return(EMPTY_RETURN.c_str());
}
// Found the object, so return the PG Tag.
return(pg->getTagValue(tag));
}

References SamHeaderRecord::getTagValue().

## getReferenceID() [1/2]

int SamFileHeader::getReferenceID | ( | const char * | referenceName,
|  | bool | addID = `false`
| ) |  |

Get the reference ID for the specified reference name (chromosome).

If addID is set to true, a reference id will be created for the referenceName if one does not already exist. If addID is set to false (default), it will return SamReferenceInfo::NO_REF_ID.

Definition at line 152 of file SamFileHeader.cpp.

{
return(myReferenceInfo.getReferenceID(referenceName, addID));
}
SamReferenceInfo::getReferenceID
int getReferenceID(const String &referenceName, bool addID=false)
Get the reference ID for the specified name, if addID is set to true, a reference id will be created ...
Definition SamReferenceInfo.cpp:45

References SamReferenceInfo::getReferenceID().

## getReferenceID() [2/2]

int SamFileHeader::getReferenceID | ( | const String & | referenceName,
|  | bool | addID = `false`
| ) |  |

Get the reference ID for the specified reference name (chromosome).

If addID is set to true, a reference id will be created for the referenceName if one does not already exist. If addID is set to false (default), it will return SamReferenceInfo::NO_REF_ID.

Definition at line 146 of file SamFileHeader.cpp.

{
return(myReferenceInfo.getReferenceID(referenceName, addID));
}

References SamReferenceInfo::getReferenceID().

Referenced by SamFile::getNumMappedReadsFromIndex(), SamFile::getNumUnMappedReadsFromIndex(), SamRecord::setMateReferenceName(), and SamRecord::setReferenceName().

## getReferenceInfo()

const SamReferenceInfo & SamFileHeader::getReferenceInfo | ( |  | ) | const

Get the Reference Information.

Definition at line 165 of file SamFileHeader.cpp.

{
return(myReferenceInfo);
}

Referenced by SamValidator::isValid().

## getReferenceInfoForBamInterface()

SamReferenceInfo & SamFileHeader::getReferenceInfoForBamInterface | ( |  | ) |

Definition at line 173 of file SamFileHeader.cpp.

{
return(myReferenceInfo);
}

## getReferenceLabel()

const String & SamFileHeader::getReferenceLabel | ( | int | id | ) | const

Return the reference name (chromosome) for the specified reference id.

Definition at line 158 of file SamFileHeader.cpp.

{
return(myReferenceInfo.getReferenceLabel(id));
}
SamReferenceInfo::getReferenceLabel
const String & getReferenceLabel(int id) const
Get the reference name for the specified id, if the id is not found, return "*".
Definition SamReferenceInfo.cpp:80

References SamReferenceInfo::getReferenceLabel().

Referenced by SamFile::validateSortOrder().

## getRG()

SamHeaderRG * SamFileHeader::getRG | ( | const char * | id | ) |

Get the RG object with the specified read group identifier, returning NULL if there is no RG object with that key.

Definition at line 782 of file SamFileHeader.cpp.

{
return((SamHeaderRG*)(myRGs.Object(id)));
}

Referenced by setRGTag().

## getRGTagValue()

const char * SamFileHeader::getRGTagValue | ( | const char * | tag,
|  | const char * | id
| ) |  |

Get the value associated with the specified tag on the RG line with the specified read group identifier, returning "" if the tag or key does not exist.

Definition at line 714 of file SamFileHeader.cpp.

{
// Look up the id in the hash to get the associated RG object.
SamHeaderRG* rg = (SamHeaderRG*)(myRGs.Object(id));
// If it is NULL - the tag was not found, so return
if(rg == NULL)
{
return(EMPTY_RETURN.c_str());
}
// Found the object, so return the RG Tag.
return(rg->getTagValue(tag));
}

References SamHeaderRecord::getTagValue().

## getSortOrder()

const char * SamFileHeader::getSortOrder | ( |  | ) |

Return the Sort Order value that is set in the Header, returning "" if this field does not exist.

Definition at line 797 of file SamFileHeader.cpp.

{
if(myHD == NULL)
{
// No HD, so return blank EMPTY_RETURN.c_str()
return(EMPTY_RETURN.c_str());
}
return(myHD->getSortOrder());
}

Referenced by getTagSO().

## getSQ()

SamHeaderSQ * SamFileHeader::getSQ | ( | const char * | name | ) |

Get the SQ object with the specified sequence name, returning NULL if there is no SQ object with that key.

Definition at line 775 of file SamFileHeader.cpp.

{
return((SamHeaderSQ*)(mySQs.Object(name)));
}

Referenced by SamValidator::isValidRname(), and setSQTag().

## getSQTagValue()

const char * SamFileHeader::getSQTagValue | ( | const char * | tag,
|  | const char * | name
| ) |  |

Get the value associated with the specified tag on the SQ line with the specified sequence name, returning "" if the tag or key does not exist.

Definition at line 696 of file SamFileHeader.cpp.

{
// Look up the name in the hash to get the associated SQ object.
SamHeaderSQ* sq = (SamHeaderSQ*)(mySQs.Object(name));
// If it is NULL - the tag was not found, so return
if(sq == NULL)
{
return(EMPTY_RETURN.c_str());
}
// Found the object, so return the SQ Tag.
return(sq->getTagValue(tag));
}

References SamHeaderRecord::getTagValue().

## getTagSO()

const char * SamFileHeader::getTagSO | ( |  | ) |

DEPRECATED.

Definition at line 809 of file SamFileHeader.cpp.

{
return(getSortOrder());
}
SamFileHeader::getSortOrder
const char * getSortOrder()
Return the Sort Order value that is set in the Header, returning "" if this field does not exist.
Definition SamFileHeader.cpp:797

References getSortOrder().

## operator=()

SamFileHeader & SamFileHeader::operator= | ( | const SamFileHeader & | header | ) |

Overload operator = to copy the passed in header into this header.

Definition at line 52 of file SamFileHeader.cpp.

{
copy(header);
return(*this);
}

References copy().

## removeHD()

bool SamFileHeader::removeHD | ( |  | ) |

Remove the HD record.

Returns
  true if successfully removed or did not exist, false if the record still exists.

Definition at line 554 of file SamFileHeader.cpp.

{
if(myHD != NULL)
{
// Reset the record. Do not delete it since it is in the headerRecords
// vector and it is not worth the time to remove it from the middle of
// that vector since this is the header and the space does not need
// to be conserved.
myHD->reset();
// Set myHD to null so a new HD could be added.
myHD = NULL;
}
return(true);
}
SamHeaderRecord::reset
void reset()
Reset this header record to an empty state with no tags.
Definition SamHeaderRecord.cpp:212

References SamHeaderRecord::reset().

## removePG()

bool SamFileHeader::removePG | ( | const char * | id | ) |

Remove PG record with the specified key.

Returns
  true if successfully removed or did not exist, false if the record still exists.

Definition at line 647 of file SamFileHeader.cpp.

{
// Look up the id in the hash.
int hashIndex = myPGs.Find(id);
if(hashIndex < 0)
{
// Not found in the hash, so nothing to
// delete, return true it does not exist
// in the hash.
return(true);
}
// Get the PG.
SamHeaderPG* pg = (SamHeaderPG*)(myPGs.Object(hashIndex));
if(pg == NULL)
{
// pg is null, this is an error since hashIndex was greater than 0,
// so it should have been found.
myErrorMessage = "SAM/BAM Header line failed to get PG object.";
return(false);
}
// Reset the record. Do not delete it since it is in the headerRecords
// vector and it is not worth the time to remove it from the middle of
// that vector since this is the header and the space does not need
// to be conserved.
pg->reset();
// Delete the entry from the hash.
myPGs.Delete(hashIndex);
return(true);
}

References SamHeaderRecord::reset().

## removeRG()

bool SamFileHeader::removeRG | ( | const char * | id | ) |

Remove RG record with the specified key.

Returns
  true if successfully removed or did not exist, false if the record still exists.

Definition at line 610 of file SamFileHeader.cpp.

{
// Look up the id in the hash.
int hashIndex = myRGs.Find(id);
if(hashIndex < 0)
{
// Not found in the hash, so nothing to
// delete, return true it does not exist
// in the hash.
return(true);
}
// Get the RG.
SamHeaderRG* rg = (SamHeaderRG*)(myRGs.Object(hashIndex));
if(rg == NULL)
{
// rg is null, this is an error since hashIndex was greater than 0,
// so it should have been found.
myErrorMessage = "SAM/BAM Header line failed to get RG object.";
return(false);
}
// Reset the record. Do not delete it since it is in the headerRecords
// vector and it is not worth the time to remove it from the middle of
// that vector since this is the header and the space does not need
// to be conserved.
rg->reset();
// Delete the entry from the hash.
myRGs.Delete(hashIndex);
return(true);
}

References SamHeaderRecord::reset().

## removeSQ()

bool SamFileHeader::removeSQ | ( | const char * | name | ) |

Remove SQ record with the specified key.

NOTE: Does not remove it from the BAM index.

Returns
  true if successfully removed or did not exist, false if the record still exists.

Definition at line 573 of file SamFileHeader.cpp.

{
// Look up the name in the hash.
int hashIndex = mySQs.Find(name);
if(hashIndex < 0)
{
// Not found in the hash, so nothing to
// delete, return true it does not exist
// in the hash.
return(true);
}
// Get the SQ.
SamHeaderSQ* sq = (SamHeaderSQ*)(mySQs.Object(hashIndex));
if(sq == NULL)
{
// sq is null, this is an error since hashIndex was greater than 0,
// so it should have been found.
myErrorMessage = "SAM/BAM Header line failed to get SQ object.";
return(false);
}
// Reset the record. Do not delete it since it is in the headerRecords
// vector and it is not worth the time to remove it from the middle of
// that vector since this is the header and the space does not need
// to be conserved.
sq->reset();
// Delete the entry from the hash.
mySQs.Delete(hashIndex);
return(true);
}

References SamHeaderRecord::reset().

## resetCommentIter()

void SamFileHeader::resetCommentIter | ( |  | ) |

Resets to the beginning of the comments so getNextComment returns the first comment.

Definition at line 998 of file SamFileHeader.cpp.

{
myCurrentCommentIndex = 0;
}

Referenced by resetHeader().

## resetHeader()

void SamFileHeader::resetHeader | ( |  | ) |

Initialize the header.

Definition at line 90 of file SamFileHeader.cpp.

{
myReferenceInfo.clear();
// Clear the pointers to the header records. They are deleted when the
// vector is cleaned up.
myHD = NULL;
mySQs.Clear();
myRGs.Clear();
myPGs.Clear();
// Delete the header records and clear the vector.
for(unsigned int headerIndex = 0; headerIndex < myHeaderRecords.size();
headerIndex++)
{
if(myHeaderRecords[headerIndex] != NULL)
{
delete myHeaderRecords[headerIndex];
myHeaderRecords[headerIndex] = NULL;
}
}
myHeaderRecords.clear();
// Reset the iterator for the header lines.
resetHeaderRecordIter();
// Reset the comment iterator.
resetCommentIter();
// Reset the individual type header iterators.
resetSQRecordIter();
resetRGRecordIter();
resetPGRecordIter();
// Clear the comments
myComments.clear();
}
SamFileHeader::resetRGRecordIter
void resetRGRecordIter()
Reset to the beginning of the header records so the next call to getNextRGRecord returns the first RG...
Definition SamFileHeader.cpp:852
SamFileHeader::resetSQRecordIter
void resetSQRecordIter()
Reset to the beginning of the header records so the next call to getNextSQRecord returns the first SQ...
Definition SamFileHeader.cpp:844
SamFileHeader::resetHeaderRecordIter
void resetHeaderRecordIter()
Reset to the beginning of the header records so the next call to getNextHeaderRecord returns the firs...
Definition SamFileHeader.cpp:966
SamFileHeader::resetPGRecordIter
void resetPGRecordIter()
Reset to the beginning of the header records so the next call to getNextPGRecord returns the first PG...
Definition SamFileHeader.cpp:860
SamFileHeader::resetCommentIter
void resetCommentIter()
Resets to the beginning of the comments so getNextComment returns the first comment.
Definition SamFileHeader.cpp:998

References SamReferenceInfo::clear(), resetCommentIter(), resetHeaderRecordIter(), resetPGRecordIter(), resetRGRecordIter(), and resetSQRecordIter().

Referenced by copy().

## resetHeaderRecordIter()

void SamFileHeader::resetHeaderRecordIter | ( |  | ) |

Reset to the beginning of the header records so the next call to getNextHeaderRecord returns the first header line.

Definition at line 966 of file SamFileHeader.cpp.

{
myCurrentHeaderIndex = 0;
}

Referenced by resetHeader().

## resetPGRecordIter()

void SamFileHeader::resetPGRecordIter | ( |  | ) |

Reset to the beginning of the header records so the next call to getNextPGRecord returns the first PG header record.

Definition at line 860 of file SamFileHeader.cpp.

{
myCurrentPGIndex = 0;
}

Referenced by resetHeader().

## resetRGRecordIter()

void SamFileHeader::resetRGRecordIter | ( |  | ) |

Reset to the beginning of the header records so the next call to getNextRGRecord returns the first RG header record.

Definition at line 852 of file SamFileHeader.cpp.

{
myCurrentRGIndex = 0;
}

Referenced by resetHeader().

## resetSQRecordIter()

void SamFileHeader::resetSQRecordIter | ( |  | ) |

Reset to the beginning of the header records so the next call to getNextSQRecord returns the first SQ header record.

Definition at line 844 of file SamFileHeader.cpp.

{
myCurrentSQIndex = 0;
}

Referenced by resetHeader().

## setHDTag()

bool SamFileHeader::setHDTag | ( | const char * | tag,
|  | const char * | value
| ) |  |

Set the specified tag to the specified value in the HD header, remove the tag by specifying value="".

Returns
  true if the tag was successfully set, false if not.

Definition at line 225 of file SamFileHeader.cpp.

{
if(myHD == NULL)
{
// Need to create the HD line.
myHD = new SamHeaderHD();
if(myHD == NULL)
{
// New failed, return false.
myErrorMessage = "SamFileHeader: Failed to allocate a new HD tag";
return(false);
}
// Succeeded to create the line, add it to the
// list.
myHeaderRecords.push_back(myHD);
}
if(!myHD->setTag(tag, value))
{
myErrorMessage = "SamFileHeader: Failed to set the specified HD tag";
return(false);
}
return(true);
}
SamHeaderRecord::setTag
bool setTag(const char *tag, const char *value)
Set the value of the specified tag to the specified value, deletes the tag when value is NULL.
Definition SamHeaderRecord.cpp:119

References SamHeaderRecord::setTag().

## setPGTag()

bool SamFileHeader::setPGTag | ( | const char * | tag,
|  | const char * | value,
|  | const char * | id
| ) |  |

Set the specified tag to the specified value in the PG header with the specified id, remove the tag by specifying value="".

If the header does not yet exist, the header is added and so is the ID tag with the value set to the passed in id. The ID tag may not be modified or removed after it is set unless the entire record is deleted.

Returns
  true if the tag was successfully set, false if not.

Definition at line 353 of file SamFileHeader.cpp.

{
// Get the PG record for the specified name.
SamHeaderPG* pg = getPG(id);
if(pg == NULL)
{
// The PG does not yet exist.
// Add it.
pg = new SamHeaderPG();
if(pg == NULL)
{
// Could not create the header record.
myErrorMessage = "Failed to allocate a new PG tag";
return(false);
}
// Created the header record, so add it to the list of PG lines.
myPGs.Add(id, pg);
myHeaderRecords.push_back(pg);
// Add the key tag
if(!pg->addKey(id))
{
// Failed to add the key tag, return false.
myErrorMessage = "Failed to add the specified PG key";
return(false);
}
}
if(!pg->setTag(tag, value))
{
myErrorMessage = "Failed to set the specified PG tag";
return(false);
}
return(true);
}
SamFileHeader::getPG
SamHeaderPG * getPG(const char *id)
Get the PG object with the specified id, returning NULL if there is no PG object with that key.
Definition SamFileHeader.cpp:789
SamHeaderRecord::addKey
bool addKey(const char *value)
Add the key tag with the specified value (not for HD headers).
Definition SamHeaderRecord.cpp:273

References SamHeaderRecord::addKey(), getPG(), and SamHeaderRecord::setTag().

## setRGTag()

bool SamFileHeader::setRGTag | ( | const char * | tag,
|  | const char * | value,
|  | const char * | id
| ) |  |

Set the specified tag to the specified value in the RG header with the specified id, remove the tag by specifying value="".

If the header does not yet exist, the header is added and so is the ID tag with the value set to the passed in id. The ID tag may not be modified or removed after it is set unless the entire record is deleted.

Returns
  true if the tag was successfully set, false if not.

Definition at line 311 of file SamFileHeader.cpp.

{
// Get the RG record for the specified name.
SamHeaderRG* rg = getRG(id);
if(rg == NULL)
{
// The RG does not yet exist.
// Add it.
rg = new SamHeaderRG();
if(rg == NULL)
{
// Could not create the header record.
myErrorMessage = "Failed to allocate a new RG tag";
return(false);
}
// Created the header record, so add it to the list of RG lines.
myRGs.Add(id, rg);
myHeaderRecords.push_back(rg);
// Add the key tag
if(!rg->addKey(id))
{
// Failed to add the key tag, return false.
myErrorMessage = "Failed to add the specified RG key";
return(false);
}
}
if(!rg->setTag(tag, value))
{
myErrorMessage = "Failed to set the specified RG tag";
return(false);
}
return(true);
}
SamFileHeader::getRG
SamHeaderRG * getRG(const char *id)
Get the RG object with the specified read group identifier, returning NULL if there is no RG object w...
Definition SamFileHeader.cpp:782

References SamHeaderRecord::addKey(), getRG(), and SamHeaderRecord::setTag().

## setSQTag()

bool SamFileHeader::setSQTag | ( | const char * | tag,
|  | const char * | value,
|  | const char * | name
| ) |  |

Set the specified tag to the specified value in the SQ header with the specified name, remove the tag by specifying value="".

If the header does not yet exist, the tag must be "LN" and the header is added with the specified LN value and the SN value passed in name.
The SN & LN tags may not be modified or removed after they are set unless the entire record is deleted.

Returns
  true if the tag was successfully set, false if not.

Definition at line 252 of file SamFileHeader.cpp.

{
// Get the SQ record for the specified name.
SamHeaderSQ* sq = getSQ(name);
if(sq == NULL)
{
// The SQ does not yet exist.
// Make sure the tag is LN.
if(strcmp(tag, "LN") != 0)
{
// LN is required so must be the first tag added
myErrorMessage =
"SamFileHeader:Failed to add the specified SQ key, LN not specified.";
return(false);
}
// Add it.
sq = new SamHeaderSQ();
if(sq == NULL)
{
// Could not create the header record.
myErrorMessage = "SamFileHeader: Failed to allocate a new SQ tag";
return(false);
}
// Created the header record, so add it to the list of SQ lines.
mySQs.Add(name, sq);
myHeaderRecords.push_back(sq);
// value is the length, so update the reference info.
myReferenceInfo.add(name, atoi(value));
// Add the key tag
if(!sq->addKey(name))
{
// Failed to add the key tag, return false.
myErrorMessage = "SamFileHeader:Failed to add the specified SQ key";
return(false);
}
}
else if(strcmp(tag, "LN") == 0)
{
// Cannot modify/remove the LN tag.
myErrorMessage = "SamFileHeader:Cannot modify/remove the SQ's LN tag";
return(false);
}
if(!sq->setTag(tag, value))
{
myErrorMessage = "Failed to set the specified SQ tag";
return(false);
}
return(true);
}
SamFileHeader::getSQ
SamHeaderSQ * getSQ(const char *name)
Get the SQ object with the specified sequence name, returning NULL if there is no SQ object with that...
Definition SamFileHeader.cpp:775

References SamReferenceInfo::add(), SamHeaderRecord::addKey(), getSQ(), and SamHeaderRecord::setTag().

## Member Data Documentation

## EMPTY_RETURN

const std::string SamFileHeader::EMPTY_RETURN = ""

static

Definition at line 425 of file SamFileHeader.h.

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

- bam/SamFileHeader.h
- bam/SamFileHeader.cpp