| Line 1: |
Line 1: |
| | + | [[Category:C++]] |
| | + | [[Category:libStatGen]] |
| | + | [[Category:libStatGen BAM]] |
| | + | |
| | == SamFileHeader == | | == SamFileHeader == |
| | This class allows a user to get/set the fields in a SAM/BAM Header. | | This class allows a user to get/set the fields in a SAM/BAM Header. |
| | | | |
| − | This class is part of [[C++ Library: libbam|libbam]]. | + | This class is part of [[C++ Library: libStatGen]]. |
| | | | |
| | === Sam Header Basics === | | === Sam Header Basics === |
| − | The SamFileHeader is comprised of multiple [[C++ Class: SamHeaderRecord|SamHeaderRecords]]. | + | The SamFileHeader is comprised of multiple [http://csg.sph.umich.edu//mktrost/doxygen/current/classSamHeaderRecord.html SamHeaderRecords]. |
| | | | |
| | There are 4 types of SAM Header Records: | | There are 4 types of SAM Header Records: |
| Line 15: |
Line 19: |
| | A SAM Header Record is comprised of Tag/Value pairs. Each tag only appears once within a specific record. | | A SAM Header Record is comprised of Tag/Value pairs. Each tag only appears once within a specific record. |
| | | | |
| − | A SAM Header can have 0 or 1 HD records, 0 or 1 PG records, 0 or more SQ Records, and 0 or more RG records. The SQ records are keyed off of the SN, Sequence Name, tag. This tag must be unique between SQ records. The RG records are keyed off of the ID, Unique Read Group Identifier, tag. This tag must be unique between SQ records. | + | A SAM Header can have 0 or 1 HD records, 0 or more PG records, 0 or more SQ Records, and 0 or more RG records. The PG records are keyed off of the ID tag. The SQ records are keyed off of the SN, Sequence Name, tag. The RG records are keyed off of the ID, Unique Read Group Identifier, tag. The keys must be unique for that record type within the file. |
| − | | |
| − | The SamFileHeader also contains Comments, type CO. They are not included as part of the SamHeaderRecord class since they do not contain Tag/Value pairs.
| |
| − | | |
| − | === Setting fields in the Header ===
| |
| − | The '''SamFileHeader''' class contains accessors to set the header lines of a SAM/BAM header. By using these set methods to setup the header, they can be pulled back out using the get accessors or the header can be later written to a SAM/BAM file.
| |
| − | | |
| − | ==== Adding an entire Header Line ====
| |
| − | The methods found in the '''SamFileHeader''' class for setting an entire header record are:
| |
| − | {| style="margin: 1em 1em 1em 0; background-color: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;" border="1"
| |
| − | |-style="background: #f2f2f2; text-align: center;" '''SamFileHeader Class Methods'''
| |
| − | ! Method Name !! Description
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::addHeaderLine(const char* type, const char* tag, const char* value)</code>
| |
| − | | Adds the type, tag, and const char* value to the header.
| |
| − | Returns true if successfully added, false if not.
| |
| − | | |
| − | NOTE: currently, this method will only do one tag per type on a line. If a type has multiple tags, then the whole line needs to be added at once.
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::addHeaderLine(const char* headerLine)</code>
| |
| − | | Adds the already setup/formatted headerLine to the header. It is assumed that the line does not contain a “\n”.
| |
| − | Returns true if successfully added, false if not.
| |
| − | |}
| |
| − | | |
| − | ==== Set/Add/Remove a Single Tag ====
| |
| − | NOTE: A tag is removed by setting it to ""
| |
| − | | |
| − | NOTE: For the SQ header type, the SN tag may not be modified once it is set, and for the RG header type, the ID tag may not be modified once it is set. That is because these values are used as a lookup key for the header record.
| |
| − | | |
| − | {| style="margin: 1em 1em 1em 0; background-color: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;" border="1"
| |
| − | |-style="background: #f2f2f2; text-align: center;" '''SamFileHeader Class Methods'''
| |
| − | ! Method Name !! Description
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::setHDTag(const char* tag, const char* value)</code>
| |
| − | | Set the specified tag to the specified value in the HD header. A tag is removed by passing in value = "".
| |
| − | Returns true if the tag was successfully set.
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::setPGTag(const char* tag, const char* value)</code>
| |
| − | | Set the specified tag to the specified value in the PG header.
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::setSQTag(const char* tag, const char* value, const char* name)</code>
| |
| − | | Set the specified tag to the specified value in the SQ header with the specified name. If the header does not yet exist, the header is added and so is the SN tag with the value set to the passed in name. A tag is removed by passing in value = "". The SN tag may not be modified or removed after it is set.
| |
| − | Returns true if the tag was successfully set.
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::setRGTag(const char* tag, const char* value, const char* id)</code>
| |
| − | | Set the specified tag to the specified value in the RG header with the specified id. 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. A tag is removed by passing in value = "". The ID tag may not be modified or removed after it is set.
| |
| − | Returns true if the tag was successfully set.
| |
| − | |}
| |
| − | | |
| − | ==== Add an Already Setup SamHeaderRecord ====
| |
| − | NOTE: These methods add a pointer to the passed in record. The header record will be deleted when it is cleaned up from this header.
| |
| − | | |
| − | NOTE: Do NOT delete the passed in record, the SamFileHeader class takes care of that itself.
| |
| − | | |
| − | {| style="margin: 1em 1em 1em 0; background-color: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;" border="1"
| |
| − | |-style="background: #f2f2f2; text-align: center;" '''SamFileHeader Class Methods'''
| |
| − | ! Method Name !! Description
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::addHD(SamHeaderHD* hd)</code>
| |
| − | | Add the HD record to the header.
| |
| − | Returns true if the record was successfully added.
| |
| − | |-
| |
| − | | <code> bool SamFileHeader::addPG(SamHeaderPG* pg)</code>
| |
| − | | Add the PG record to the header.
| |
| − | Returns true if the record was successfully added.
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::addSQ(SamHeaderSQ* sq)</code>
| |
| − | | Add the SQ record to the header.
| |
| − | Returns true if the record was successfully added.
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::addRG(SamHeaderRG* rg)</code>
| |
| − | |Add the SQ record to the header.
| |
| − | Returns true if the record was successfully added.
| |
| − | |}
| |
| − | | |
| − | ==== Remove an Entire Header Record ====
| |
| − | {| style="margin: 1em 1em 1em 0; background-color: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;" border="1"
| |
| − | |-style="background: #f2f2f2; text-align: center;" '''SamFileHeader Class Methods'''
| |
| − | ! Method Name !! Description
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::removeHD()</code>
| |
| − | | Remove the HD record.
| |
| − | Returns true if successfully removed or if it didn't exist in the first place. Returns false if the record still exists.
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::removePG()</code>
| |
| − | | Remove the PG record.
| |
| − | Returns true if successfully removed or if it didn't exist in the first place. Returns false if the record still exists.
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::removeSQ(const char* name)</code>
| |
| − | | Remove the SQ record associated with the specified name.
| |
| − | Returns true if successfully removed or if it didn't exist in the first place. Returns false if the record still exists.
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::removeRG(const char* id)</code>
| |
| − | | Remove the RG record associated with the specified id.
| |
| − | Returns true if successfully removed or if it didn't exist in the first place. Returns false if the record still exists.
| |
| − | |}
| |
| − | | |
| − | | |
| − | === Getting fields from the Header ===
| |
| | | | |
| − | {| style="margin: 1em 1em 1em 0; background-color: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;" border="1"
| + | The '''SamFileHeader''' also contains Comments, type CO. They are not included as part of the '''SamHeaderRecord''' class since they do not contain Tag/Value pairs. |
| − | |-style="background: #f2f2f2; text-align: center;" '''SamFileHeader Class Methods'''
| |
| − | ! Method Name !! Description
| |
| − | |-
| |
| − | | <code>bool SamFileHeader::getHeaderString(std::string& header)</code>
| |
| − | | Set the passed in string to the entire header string. Clearing its current contents.
| |
| − | Returns true if successfully set (even if set to "")
| |
| − | |-
| |
| − | | <code>const char* SamFileHeader::getTagSO()</code>
| |
| − | | Return the value of the SO tag. If the field does not exist, "unsorted" is returned.
| |
| − | |}
| |
| | | | |
| | + | See: http://csg.sph.umich.edu//mktrost/doxygen/current/classSamFileHeader.html for documentation. |
| | | | |
| − | ==== Proposed Accessors ==== | + | ==== Additional Proposed Accessors ==== |
| | * HD | | * HD |
| | ** getVersion - returns the VN field (will only be one) | | ** getVersion - returns the VN field (will only be one) |
