Line 12: |
Line 12: |
| This class is part of [[C++ Library: libStatGen|C++ Library: libStatGen]]. | | This class is part of [[C++ Library: libStatGen|C++ Library: libStatGen]]. |
| | | |
− | === Class Methods === | + | === Class Documentation === |
− | | |
− | {| style="margin: 1em 1em 1em 0; background-color: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;" border="1"
| |
− | |-style="background: #f2f2f2; text-align: center;"
| |
− | ! Method Name !! Description
| |
− | |-
| |
− | | <code>SamFile::SamFile()</code>
| |
− | | Default Constructor - initializes the variables, but does not open any files.
| |
− | |-
| |
− | | <code>SamFile::SamFile(const char* filename, OpenType mode = READ)</code>
| |
− | | Constructor - initializes the variables, and opens the specified file for READ/WRITE based on the passed in mode. If the mode is not specified, it defaults to READ.
| |
− | Aborts if the specified file could not be opened.
| |
− | |-
| |
− | | <code>bool SamFile::IsEOF()</code>
| |
− | | bool: true if the end of file has been reached, false if not.
| |
− | Be careful using this method when you are only reading a specific section since you may reach the end of your section without hitting the end of the file
| |
− | |-
| |
− | | <code>bool SamFile::OpenForRead(const char* filename)</code>
| |
− | | Opens the specified file for reading.
| |
− | Determines if it is a BAM/SAM file by reading the beginning of the file.
| |
− | Returns true if successfully opened reading, false if not.
| |
− | |-
| |
− | | <code>bool SamFile::OpenForWrite(const char * filename)</code>
| |
− | | bool: true if successfully opened, false if not.
| |
− | Opens as BAM file if the specified filename ends in .bam. Otherwise it is opened as a SAM file.
| |
− | Returns true if successfully opened for writing, false if not.
| |
− | |-
| |
− | | <code>bool SamFile::ReadBamIndex(const char * filename)</code>
| |
− | | bool: true if the bam index file was successfully read, false if not.
| |
− | Reads the specified bam index file. It must be read prior to setting a read section, for seeking and reading portions of a bam file.
| |
− | |-
| |
− | | <code>void SamFile::Close()</code>
| |
− | | Close the file if there is one open.
| |
− | |-
| |
− | | <code>bool SamFile::ReadHeader(SamFileHeader& header)</code>
| |
− | | Reads the header section from the file and stores it in the passed in header.
| |
− | Returns true if successfully read, false if not.
| |
− | |-
| |
− | | <code>bool SamFile::WriteHeader(SamFileHeader& header)</code>
| |
− | | Writes the specified header into the file.
| |
− | Returns true if successfully written, false if not.
| |
− | |-
| |
− | | <code>bool SamFile::ReadRecord(SamFileHeader& header, SamRecord& record)</code>
| |
− | | Reads the next record from the file and stores it in the passed in record.
| |
− | | |
− | If it is an indexed BAM file and SetReadSection was called, only alignments in the section specified by <code>SetReadSection</code> are read. If they all have already been read, this method returns false.
| |
− | | |
− | Validates that the record is sorted according to the value set by <code>setSortedValidation</code>. No sorting validation is done if specified to be unsorted, or <code>setSortedValidation</code> was never called.
| |
− | | |
− | Returns false if the record was not successfully read or not properly sorted. Returns true if successfully read and properly sorted.
| |
− | |-
| |
− | | <code>bool SamFile::WriteRecord(SamFileHeader& header, SamRecord& record)</code>
| |
− | | Writes the specified record into the file.
| |
− | Validates that the record is sorted according to the value set by <code>setSortedValidation</code>. No sorting validation is done if specified to be unsorted, or <code>setSortedValidation</code> was never called. Returns false and does not write the record if the record was not properly sorted.
| |
− | | |
− | Returns false if the record was not properly sorted or not successfully written. Returns true if properly sorted and successfully written.
| |
− | |-
| |
− | | <code>void SamFile::setSortedValidation(SortedType sortType)<\code>
| |
− | | Set the flag to validate that the file is sorted as it is read/written. Must be called after the file has been opened.
| |
− | sortType specifies the type of sort to be checked for.
| |
− | |-
| |
− | | <code>uint32_t SamFile::GetCurrentRecordCount()</code>
| |
− | | Return the number of records that have been read/written so far.
| |
− | |-
| |
− | | <code>SamStatus::Status SamFile::GetStatus()</code>
| |
− | | Get the status result of the last status reporting method call.
| |
− | |-
| |
− | | <code>const char* SamFile::GetStatusMessage()</code>
| |
− | | Get the Status Message of the last call that sets status.
| |
− | |-
| |
− | | '''DEPRECATED: '''<code>SamStatus::Status SamFile::GetFailure()</code>
| |
− | | Get the type of failure that occurred on a method failure.
| |
− | |-
| |
− | | <code>bool SamFile::SetReadSection(int32_t refID)</code>
| |
− | | Tell the class which reference ID should be read from the BAM file. This is the index into the BAM Index list of reference information: 0 - #references. The records for that reference id will be retrieved on each <code>ReadRecord</code> call. When all records have been retrieved for the specified reference id, <code>ReadRecord</code> will return false until a new read section is set.
| |
− | Pass in -1 in order to read the section of the bam file not associated with any reference ID.
| |
− | | |
− | Must be called after <code>OpenForRead</code>.
| |
− | | |
− | Returns true if the read section was successfully set, false if not. False is returned if the BAM Index File has not yet been read or if a BAM file is not open for reading.
| |
− | |-
| |
− | | <code>bool SamFile::SetReadSection(const char* refName)</code>
| |
− | | Tell the class which reference name should be read from the BAM file. The specified name will be mapped to the index into the BAM Index list of reference information: 0 - #references. The records for that reference name will be retrieved on each <code>ReadRecord</code> call. When all records have been retrieved for the specified reference name, <code>ReadRecord</code> will return false until a new read section is set.
| |
− | Pass in "" or "*" in order to read the section of the bam file not associated with any reference name.
| |
− | | |
− | Must be called after <code>OpenForRead</code>.
| |
− | | |
− | Returns true if the read section was successfully set, false if not. False is returned if the BAM Index File has not yet been read or if a BAM file is not open for reading.
| |
− | |-
| |
− | | <code>bool SamFile::SetReadSection(int32_t refID, int32_t start, int32_t end)</code>
| |
− | | Sets what part of the BAM file should be read. Fails if this is not a BAM file &/or the index file has not yet been read. This version will set it to only read a specific reference id and 0-based start(inclusive)/end(exclusive) region. The records for this section will be retrieved on each <code>ReadRecord</code> call. When all records have been retrieved for the specified section, ReadRecord will return failure until a new read section is set.
| |
− | Pass in -1 in order to read the section of the bam file not associated with any reference ID.
| |
− | | |
− | Must be called after <code>OpenForRead</code>.
| |
− | | |
− | Return Value: true = success; false = failure.
| |
− | |-
| |
− | | <code>bool SamFile::SetReadSection(const char* refName, int32_t start, int32_t end)</code>
| |
− | | Sets what part of the BAM file should be read. Fails if this is not a BAM file &/or the index file has not yet been read. This version will set it to only read a specific reference name and 0-based start(inclusive)/end(exclusive) region. The records for this section will be retrieved on each <code>ReadRecord</code> call. When all records have been retrieved for the specified section, ReadRecord will return failure until a new read section is set.
| |
− | Pass in "" or "*" in order to read the section of the bam file not associated with any reference name.
| |
− | | |
− | Must be called after <code>OpenForRead</code>.
| |
− | | |
− | Return Value: true = success; false = failure.
| |
− | |-
| |
− | | <code>uint32_t SamFile::GetNumOverlaps(SamRecord& samRecord)</code>
| |
− | | Returns the number of bases in the passed in read that overlap the region that is currently set for this file.
| |
− | Overlapping means that the bases occur in both the read and the reference as either matches or mismatches. This does not count insertions, deletions, clips, pads, or skips.
| |
− | |-
| |
− | | <code>void SamFile::GenerateStatistics(bool genStats)</code>
| |
− | | Set this SamFile class to record statistic information as records are read from the file.
| |
− | |-
| |
− | | <code>inline void SamFile::PrintStatistics()</code>
| |
− | | Print the statistics that have been recorded (by calling GenerateStatistics)
| |
− | |}
| |
− | | |
− | === Class Enums ===
| |
− | {| style="margin: 1em 1em 1em 0; background-color: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;" border="1"
| |
− | |-style="background: #f2f2f2; text-align: center;"
| |
− | ! colspan="2"| enum OpenType
| |
− | |-
| |
− | ! Enum Value !! Description
| |
− | |-
| |
− | | READ
| |
− | | Open the file for read.
| |
− | |-
| |
− | | WRITE
| |
− | | Open the file for write.
| |
− | |-style="background: #f2f2f2; text-align: center;"
| |
− | ! colspan="2"| enum SortedType
| |
− | |-
| |
− | ! Enum Value !! Description
| |
− | |-
| |
− | | UNSORTED
| |
− | | Do not do any sorting validation.
| |
− | |-
| |
− | | FLAG
| |
− | | Validate that the file is sorted by the type specified in the SO Tag of the file's header.
| |
− | |-
| |
− | | COORDINATE
| |
− | | Validate that the file is sorted by Coordinate.
| |
− | |-
| |
− | | QUERY_NAME
| |
− | | Validate that the file is sorted by Query Name.
| |
− | |}
| |
| | | |
| + | See: http://www.sph.umich.edu/csg/mktrost/doxygen/current/classSamFile.html |
| | | |
| == Child Classes == | | == Child Classes == |
− |
| |
| === SamFileReader === | | === SamFileReader === |
− | | + | http://www.sph.umich.edu/csg/mktrost/doxygen/current/classSamFileReader.html |
− | {| style="margin: 1em 1em 1em 0; background-color: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;" border="1"
| |
− | |+ '''Additional Child Class Methods'''
| |
− | |-style="background: #f2f2f2; text-align: center;"
| |
− | ! Method Name !! Description
| |
− | |-
| |
− | | <code>SamFileReader::SamFileReader(const char* filename)</code>
| |
− | | Constructor - initializes the variables, and opens the specified file for reading.
| |
− | Aborts if the specified file could not be opened.
| |
− | |}
| |
| | | |
| === SamFileWriter === | | === SamFileWriter === |
− | | + | http://www.sph.umich.edu/csg/mktrost/doxygen/current/classSamFileWriter.html |
− | {| style="margin: 1em 1em 1em 0; background-color: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;" border="1"
| |
− | |+ '''Additional Child Class Methods'''
| |
− | |-style="background: #f2f2f2; text-align: center;"
| |
− | ! Method Name !! Description
| |
− | |-
| |
− | | <code>SamFileWriter::SamFileWriter(const char* filename)</code>
| |
− | | Constructor - initializes the variables, and opens the specified file for writing.
| |
− | Aborts if the specified file could not be opened.
| |
− | |}
| |
− | | |
| | | |
| == Statistics == | | == Statistics == |