SamFile.h

/*
 *  Copyright (C) 2010  Regents of the University of Michigan
 *
 *   This program is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef __SAM_FILE_H__
#define __SAM_FILE_H__
 
#include "SamStatus.h"
#include "InputFile.h"
#include "SamFileHeader.h"
#include "SamRecord.h"
#include "GenericSamInterface.h"
#include "BamIndex.h"
#include "SamStatistics.h"
 
/// Allows the user to easily read/write a SAM/BAM file.
/// The SamFile class contains additional functionality that allows a user
/// to read specific sections of sorted & indexed BAM files.  In order to
/// take advantage of this capability, the index file must be read prior to
/// setting the read section.  This logic saves the time of having to read
/// the entire file and takes advantage of the seeking capability of BGZF.
class SamFile
{
public:
    /// Enum for indicating whether to open the file for read or write.
    enum OpenType {
        READ, ///< open for reading.
        WRITE ///< open for writing.
    };
    
    
    /// Enum for indicating the type of sort expected in the file.
    enum SortedType {
        UNSORTED = 0, ///< file is not sorted.
        FLAG,         ///< SO flag from the header indicates the sort type.
        COORDINATE,   ///< file is sorted by coordinate.
        QUERY_NAME    ///< file is sorted by queryname.
    };
    
    /// Default Constructor, initializes the variables, but does not open
    /// any files.
    SamFile();
 
    /// Constructor that sets the error handling type.
    /// \param errorHandlingType how to handle errors.
    SamFile(ErrorHandler::HandlingType errorHandlingType);
 
    /// Constructor that opens the specified file based on the specified mode
    /// (READ/WRITE), aborts if the file could not be opened.
    /// \param filename name of the file to open.
    /// \param mode mode to use for opening the file.
    SamFile(const char* filename, OpenType mode);
 
    /// Constructor that opens the specified file based on the specified mode
    /// (READ/WRITE) and handles errors per the specified handleType.
    /// \param filename name of the file to open.
    /// \param mode mode to use for opening the file.
    /// \param errorHandlingType how to handle errors.
    SamFile(const char* filename, OpenType mode,
            ErrorHandler::HandlingType errorHandlingType);
 
    /// Constructor that opens the specified file based on the specified mode
    /// (READ/WRITE) and reads the header, aborts if the file could not be
    /// opened or the header not read.
    /// \param filename name of the file to open.
    /// \param mode mode to use for opening the file.
    /// \param header to read into or write from
    SamFile(const char* filename, OpenType mode, SamFileHeader* header);
 
    /// Constructor that opens the specified file based on the specified mode
    /// (READ/WRITE) and reads the header, handling errors per the specified
    /// handleType.
    /// \param filename name of the file to open.
    /// \param mode mode to use for opening the file.
    /// \param errorHandlingType how to handle errors.
    /// \param header to read into or write from
    SamFile(const char* filename, OpenType mode,
            ErrorHandler::HandlingType errorHandlingType,
            SamFileHeader* header);
 
    /// Destructor
    virtual ~SamFile();
   
    /// Open a sam/bam file for reading with the specified filename,
    /// determing the type of file and SAM/BAM  by reading the file
    /// (if not stdin).
    /// \param  filename the sam/bam file to open for reading.
    /// \param header to read into or write from (optional)
    /// \return true = success; false = failure.
    bool OpenForRead(const char * filename, SamFileHeader* header = NULL);
 
    /// Open a sam/bam file for writing with the specified filename,
    /// determining SAM/BAM from the extension (.bam = BAM).
    /// \param  filename the sam/bam file to open for writing.
    /// \param header to read into or write from (optional)
    /// \return true = success; false = failure.
    bool OpenForWrite(const char * filename, SamFileHeader* header = NULL);
 
    /// Read the specified bam index file.  It must be read prior to setting a
    /// read section, for seeking and reading portions of a bam file.
    /// \param filename the name of the bam index file to be read.
    /// \return true = success; false = failure.
    bool ReadBamIndex(const char * filename);
 
    /// Read the bam index file using the BAM filename as a base. 
    /// It must be read prior to setting a read section, for seeking
    /// and reading portions of a bam file.
    /// Must be read after opening the BAM file since it uses the
    /// BAM filename as a base name for the index file.
    /// First it tries filename.bam.bai. If that fails, it tries
    /// it without the .bam extension, filename.bai.
    /// \return true = success; false = failure.
    bool ReadBamIndex();
 
    /// Sets the reference to the specified genome sequence object.
    /// \param reference pointer to the GenomeSequence object.
    void SetReference(GenomeSequence* reference);
 
    /// Set the type of sequence translation to use when reading
    /// the sequence.  Passed down to the SamRecord when it is read.  
    /// The default type (if this method is never called) is
    /// NONE (the sequence is left as-is).
    /// \param translation type of sequence translation to use.
    void SetReadSequenceTranslation(SamRecord::SequenceTranslation translation);
 
    /// Set the type of sequence translation to use when writing
    /// the sequence.  Passed down to the SamRecord when it is written.
    /// The default type (if this method is never called) is
    /// NONE (the sequence is left as-is).
    /// \param translation type of sequence translation to use.
    void SetWriteSequenceTranslation(SamRecord::SequenceTranslation translation);
 
    /// Close the file if there is one open.
    void Close();
 
    /// Returns whether or not the file has been opened successfully.
    /// \return true = open; false = not open.
    bool IsOpen();
   
    /// Returns whether or not the end of the file has been reached.
    /// \return true = EOF; false = not eof.
    /// If the file is not open, true is returned.
    bool IsEOF();
   
    /// Returns whether or not the file has been opened for streaming 
    /// input/output.
    /// \return true = stream; false = not a stream.
    bool IsStream();
 
    /// Reads the header section from the file and stores it in
    /// the passed in header.
    /// \return true = success; false = failure.
    bool ReadHeader(SamFileHeader& header);
   
    /// Writes the specified header into the file.
    /// \return true = success; false = failure.
    bool WriteHeader(SamFileHeader& header);
 
    /// Reads the next record from the file & 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 SetReadSection 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
    /// setSortedValidation. No sorting validation is done if specified to be
    /// unsorted, or setSortedValidation was never called.
    /// \return true  = record was successfully set (and sorted if applicable),
    ///                false = record was not successfully set 
    ///                (or not sorted as expected).
    bool ReadRecord(SamFileHeader& header, SamRecord& record);
   
    /// Writes the specified record into the file.
    /// Validates that the record is sorted according to the value set by
    /// setSortedValidation. No sorting validation is done if specified to
    /// be unsorted, or setSortedValidation was never called.  Returns false
    /// and does not write the record if the record was not properly sorted.
    /// \return true = success; false = failure.
    bool WriteRecord(SamFileHeader& header, SamRecord& record);
   
    /// Set the flag to validate that the file is sorted as it is read/written.
    /// Must be called after the file has been opened.
    /// Sorting validation is reset everytime SetReadPosition is called since
    /// it can jump around in the file.
    /// \param sortType specifies the type of sort to be checked for.
    void setSortedValidation(SortedType sortType);
 
    /// Return the number of records that have been read/written so far.
    uint32_t GetCurrentRecordCount();
 
    /// Deprecated, get the Status of the last call that sets status.
    /// To remain backwards compatable - will be removed later.
    inline SamStatus::Status GetFailure()
    {
        return(GetStatus());
    }
 
    /// Get the Status of the last call that sets status.
    inline SamStatus::Status GetStatus()
    {