SamFile Class Reference

Allows the user to easily read/write a SAM/BAM file. More...

#include <SamFile.h>

Inheritance diagram for SamFile:

[legend]

Collaboration diagram for SamFile:

[legend]

List of all members.

Public Types
enum	OpenType { READ, WRITE }
	Enum for indicating whether to open the file for read or write. More...
enum	SortedType { UNSORTED = 0, FLAG, COORDINATE, QUERY_NAME }
	Enum for indicating the type of sort for the file. More...
Public Member Functions
	SamFile ()
	Default Constructor.
	SamFile (ErrorHandler::HandlingType errorHandlingType)
	Constructor that sets the error handling type.
	SamFile (const char *filename, OpenType mode)
	Constructor that opens the specified file based on the specified mode (READ/WRITE).
	SamFile (const char *filename, OpenType mode, ErrorHandler::HandlingType errorHandlingType)
	Constructor that opens the specified file based on the specified mode (READ/WRITE) and handles errors per the specified handleType.
bool	OpenForRead (const char *filename)
	Open a sam/bam file for reading with the specified filename.
bool	OpenForWrite (const char *filename)
	Open a sam/bam file for writing with the specified filename.
bool	ReadBamIndex (const char *filename)
	Reads the specified bam index file.
void	SetReference (GenomeSequence *reference)
	Sets the reference to the specified genome sequence object.
void	SetReadSequenceTranslation (SamRecord::SequenceTranslation translation)
	Set the type of sequence translation to use when reading the sequence.
void	SetWriteSequenceTranslation (SamRecord::SequenceTranslation translation)
	Set the type of sequence translation to use when writing the sequence.
void	Close ()
	Close the file if there is one open.
bool	IsEOF ()
	Returns whether or not the end of the file has been reached.
bool	ReadHeader (SamFileHeader &header)
	Reads the header section from the file and stores it in the passed in header.
bool	WriteHeader (SamFileHeader &header)
	Writes the specified header into the file.
bool	ReadRecord (SamFileHeader &header, SamRecord &record)
	Reads the next record from the file & stores it in the passed in record.
bool	WriteRecord (SamFileHeader &header, SamRecord &record)
	Writes the specified record into the file.
void	setSortedValidation (SortedType sortType)
	Set the flag to validate that the file is sorted as it is read/written.
uint32_t	GetCurrentRecordCount ()
	Return the number of records that have been read/written so far.
SamStatus::Status	GetFailure ()
	Get the Status of the last call that sets status.
SamStatus::Status	GetStatus ()
	Get the Status of the last call that sets status.
const char *	GetStatusMessage ()
	Get the Status of the last call that sets status.
bool	SetReadSection (int32_t refID)
	Sets what part of the BAM file should be read.
bool	SetReadSection (const char *refName)
	Sets what part of the BAM file should be read.
bool	SetReadSection (int32_t refID, int32_t start, int32_t end)
	Sets what part of the BAM file should be read.
bool	SetReadSection (const char *refName, int32_t start, int32_t end)
	Sets what part of the BAM file should be read.
uint32_t	GetNumOverlaps (SamRecord &samRecord)
	Returns the number of bases in the passed in read that overlap the region that is currently set.
void	GenerateStatistics (bool genStats)
	Whether or not statistics should be generated for this file.
void	PrintStatistics ()
Protected Member Functions
void	resetFile ()
	Resets the file prepping for a new file.
bool	validateSortOrder (SamRecord &record, SamFileHeader &header)
	Validate that the record is sorted compared to the previously read record if there is one, according to the specified sort order.
SortedType	getSortOrderFromHeader (SamFileHeader &header)
bool	readIndexedRecord (SamFileHeader &header, SamRecord &record)
	Overwrites read record to read from the specific reference only.
bool	processNewSection (SamFileHeader &header)
Protected Attributes
IFILE	myFilePtr
GenericSamInterface *	myInterfacePtr
bool	myIsOpenForRead
	Flag to indicate if a file is open for reading.
bool	myIsOpenForWrite
	Flag to indicate if a file is open for writing.
bool	myHasHeader
	Flag to indicate if a header has been read/written - required before being able to read/write a record.
SortedType	mySortedType
int32_t	myPrevCoord
	Previous values used for checking if the file is sorted.
int32_t	myPrevRefID
std::string	myPrevReadName
uint32_t	myRecordCount
	Keep a count of the number of records that have been read/written so far.
SamStatistics *	myStatistics
	Pointer to the statistics for this file.
SamStatus	myStatus
	The status of the last SamFile command.
bool	myIsBamOpenForRead
	Values for reading Sorted BAM files via the index.
bool	myNewSection
int32_t	myRefID
int32_t	myStartPos
int32_t	myEndPos
uint64_t	myCurrentChunkEnd
SortedChunkList	myChunksToRead
BamIndex *	myBamIndex
GenomeSequence *	myRefPtr
SamRecord::SequenceTranslation	myReadTranslation
SamRecord::SequenceTranslation	myWriteTranslation
std::string	myRefName

---

Detailed Description

Allows the user to easily read/write a SAM/BAM file.

Definition at line 30 of file SamFile.h.

---

Member Enumeration Documentation

enum SamFile::OpenType

Enum for indicating whether to open the file for read or write.

Enumerator:

READ	open for reading.
WRITE	open for writing.

Definition at line 34 of file SamFile.h.

                  {
        READ, ///< open for reading.
        WRITE ///< open for writing.
    };

enum SamFile::SortedType

Enum for indicating the type of sort for the file.

Enumerator:

UNSORTED	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.

Definition at line 41 of file SamFile.h.

                    {
        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.
    };

---

Constructor & Destructor Documentation

SamFile::SamFile

(

ErrorHandler::HandlingType

errorHandlingType

)

Constructor that sets the error handling type.

Parameters:

errorHandlingType

how to handle errors.

Definition at line 40 of file SamFile.cpp.

References resetFile().

    : myFilePtr(NULL),
      myInterfacePtr(NULL),
      myStatistics(NULL),
      myStatus(errorHandlingType),
      myBamIndex(NULL),
      myRefPtr(NULL),
      myReadTranslation(SamRecord::NONE),
      myWriteTranslation(SamRecord::NONE)
{
    resetFile();
}

SamFile::SamFile	(	const char *	filename,
		OpenType	mode
	)

Constructor that opens the specified file based on the specified mode (READ/WRITE).

Parameters:

	filename	name of the file to open.
	mode	mode to use for opening the file.

Definition at line 56 of file SamFile.cpp.

References GetStatusMessage(), OpenForRead(), OpenForWrite(), READ, and resetFile().

    : myFilePtr(NULL),
      myInterfacePtr(NULL),
      myStatistics(NULL),
      myStatus(),
      myBamIndex(NULL),
      myRefPtr(NULL),
      myReadTranslation(SamRecord::NONE),
      myWriteTranslation(SamRecord::NONE)
{
    resetFile();

    bool openStatus = true;
    if(mode == READ)
    {
        // open the file for read.
        openStatus = OpenForRead(filename);
    }
    else
    {
        // open the file for write.
        openStatus = OpenForWrite(filename);
    }
    if(!openStatus)
    {
        // Failed to open the file - print error and abort.
        fprintf(stderr, "%s\n", GetStatusMessage());
        std::cerr << "FAILURE - EXITING!!!" << std::endl;
        exit(-1);
    }
}

SamFile::SamFile	(	const char *	filename,
		OpenType	mode,
		ErrorHandler::HandlingType	errorHandlingType
	)

Constructor that opens the specified file based on the specified mode (READ/WRITE) and handles errors per the specified handleType.

Parameters:

	filename	name of the file to open.
	mode	mode to use for opening the file.
	errorHandlingType	how to handle errors.

Definition at line 91 of file SamFile.cpp.

References GetStatusMessage(), OpenForRead(), OpenForWrite(), READ, and resetFile().

    : myFilePtr(NULL),
      myInterfacePtr(NULL),
      myStatistics(NULL),
      myStatus(errorHandlingType),
      myBamIndex(NULL),
      myRefPtr(NULL),
      myReadTranslation(SamRecord::NONE),
      myWriteTranslation(SamRecord::NONE)
{
    resetFile();

    bool openStatus = true;
    if(mode == READ)
    {
        // open the file for read.
        openStatus = OpenForRead(filename);
    }
    else
    {
        // open the file for write.
        openStatus = OpenForWrite(filename);
    }
    if(!openStatus)
    {
        // Failed to open the file - print error and abort.
        fprintf(stderr, "%s\n", GetStatusMessage());
        std::cerr << "FAILURE - EXITING!!!" << std::endl;
        exit(-1);
    }
}

---

Member Function Documentation

void SamFile::GenerateStatistics

(

bool

genStats

)

Whether or not statistics should be generated for this file.

The value is carried over between files and is not reset, but the statistics themselves are reset between files.

Parameters:

genStats

set to true if statistics should be generated, false if not.

Definition at line 674 of file SamFile.cpp.

References myStatistics.

{
    if(genStats)
    {
        if(myStatistics == NULL)
        {
            // Want to generate statistics, but do not yet have the
            // structure for them, so create one.
            myStatistics = new SamStatistics();
        }
    }
    else
    {
        // Do not generate statistics, so if myStatistics is not NULL, 
        // delete it.
        if(myStatistics != NULL)
        {
            delete myStatistics;
            myStatistics = NULL;
        }
    }

}

SamStatus::Status SamFile::GetFailure

(

)

[inline]

Get the Status of the last call that sets status.

To remain backwards compatable - will be removed later.

Definition at line 138 of file SamFile.h.

References GetStatus().

    {
        return(GetStatus());
    }

uint32_t SamFile::GetNumOverlaps

(

SamRecord &

samRecord

)

Returns the number of bases in the passed in read that overlap the region that is currently set.

Parameters:

samRecord

to check for overlapping bases.

Returns:

number of bases that overlap region that is currently set.

Definition at line 660 of file SamFile.cpp.

References SamRecord::getNumOverlaps(), SamRecord::setReference(), and SamRecord::setSequenceTranslation().

{
    if(myRefPtr != NULL)
    {
        samRecord.setReference(myRefPtr);
    }
    samRecord.setSequenceTranslation(myReadTranslation);

    // Get the overlaps in the sam record for the region currently set
    // for this file.
    return(samRecord.getNumOverlaps(myStartPos, myEndPos));
}

bool SamFile::IsEOF

(

)

Returns whether or not the end of the file has been reached.

Returns:

true = EOF; false = not eof. If the file is not open, false is returned.

Definition at line 356 of file SamFile.cpp.

{
    if (myFilePtr != NULL)
    {
        // File Pointer is set, so return if eof.
        return(ifeof(myFilePtr));
    }
    // File pointer is not set, so return true, eof.
    return true;
}

bool SamFile::OpenForRead

(

const char *

filename

)

Open a sam/bam file for reading with the specified filename.

Parameters:

filename,:

the sam/bam file to open for reading.

Returns:

true = success; false = failure.

Definition at line 136 of file SamFile.cpp.

References myIsBamOpenForRead, myIsOpenForRead, myStatus, and resetFile().

Referenced by SamFile(), and SamFileReader::SamFileReader().

{
    // Reset for any previously operated on files.
    resetFile();

    int lastchar = 0;

    while (filename[lastchar] != 0) lastchar++;

    // If at least one character, check for '-'.
    if((lastchar >= 1) && (filename[0] == '-'))
    {
        // Read from stdin - determine type of file to read.
        // Determine if compressed bam.
        if(strcmp(filename, "-.bam") == 0)
        {
            // Compressed bam - open as bgzf.
            // -.bam is the filename, read compressed bam from stdin
            filename = "-";
            myFilePtr = ifopen(filename, "rb", InputFile::BGZF);
            
            myInterfacePtr = new BamInterface;

            // Read the magic string.
            char magic[4];
            ifread(myFilePtr, magic, 4);
        }
        else if(strcmp(filename, "-.ubam") == 0)
        {
            // uncompressed BAM File.
            // -.ubam is the filename, read uncompressed bam from stdin
            filename = "-";
            myFilePtr = ifopen(filename, "rb", InputFile::UNCOMPRESSED);
        
            myInterfacePtr = new BamInterface;

            // Read the magic string.
            char magic[4];
            ifread(myFilePtr, magic, 4);
        }
        else
        {
            // SAM File.
            // read sam from stdin
            filename = "-";
            myFilePtr = ifopen(filename, "rb", InputFile::UNCOMPRESSED);
            myInterfacePtr = new SamInterface;
        }
    }
    else
    {
        // Not from stdin.  Read the file to determine the type.
        myFilePtr = ifopen(filename, "rb");
        
        if (myFilePtr == NULL)
        {
            std::string errorMessage = "Failed to Open ";
            errorMessage += filename;
            errorMessage += " for reading";
            myStatus.setStatus(SamStatus::FAIL_IO, errorMessage.c_str());
            return(false);
        }
        
        char magic[4];
        ifread(myFilePtr, magic, 4);
        
        if (magic[0] == 'B' && magic[1] == 'A' && magic[2] == 'M' &&
            magic[3] == 1)
        {
            myInterfacePtr = new BamInterface;
            // Set that it is a bam file open for reading.  This is needed to
            // determine if an index file can be used.
            myIsBamOpenForRead = true;
        }
        else
        {
            // Not a bam, so rewind to the beginning of the file so it
            // can be read.
            ifrewind(myFilePtr);
            myInterfacePtr = new SamInterface;
        }
    }

    // File is open for reading.
    myIsOpenForRead = true;
    // Successfully opened the file.
    myStatus = SamStatus::SUCCESS;
    return(true);
}

bool SamFile::OpenForWrite

(

const char *

filename

)

Open a sam/bam file for writing with the specified filename.

Returns:

true = success; false = failure.

Definition at line 228 of file SamFile.cpp.

References myIsOpenForWrite, myStatus, and resetFile().

Referenced by SamFile(), and SamFileWriter::SamFileWriter().

{
    // Reset for any previously operated on files.
    resetFile();
    
    int lastchar = 0;
    while (filename[lastchar] != 0) lastchar++;   
    if (lastchar >= 4 && 
        filename[lastchar - 4] == 'u' &&
        filename[lastchar - 3] == 'b' &&
        filename[lastchar - 2] == 'a' &&
        filename[lastchar - 1] == 'm')
    {
        // BAM File.
        // if -.ubam is the filename, write uncompressed bam to stdout
        if((lastchar == 6) && (filename[0] == '-') && (filename[1] == '.'))
        {
            filename = "-";
        }
        myFilePtr = ifopen(filename, "wb", InputFile::UNCOMPRESSED);

        myInterfacePtr = new BamInterface;
    }
    else if (lastchar >= 3 && 
             filename[lastchar - 3] == 'b' &&
             filename[lastchar - 2] == 'a' &&
             filename[lastchar - 1] == 'm')
    {
        // BAM File.
        // if -.bam is the filename, write compressed bam to stdout
        if((lastchar == 5) && (filename[0] == '-') && (filename[1] == '.'))
        {
            filename = "-";
        }
        myFilePtr = ifopen(filename, "wb", InputFile::BGZF);
        
        myInterfacePtr = new BamInterface;
    }
    else
    {
        // SAM File
        // if - (followed by anything is the filename,
        // write uncompressed sam to stdout
        if((lastchar >= 1) && (filename[0] == '-'))
        {
            filename = "-";
        }
        myFilePtr = ifopen(filename, "wb", InputFile::UNCOMPRESSED);
   
        myInterfacePtr = new SamInterface;
    }

    if (myFilePtr == NULL)
    {
        std::string errorMessage = "Failed to Open ";
        errorMessage += filename;
        errorMessage += " for writing";
        myStatus.setStatus(SamStatus::FAIL_IO, errorMessage.c_str());
        return(false);
    }
   
    myIsOpenForWrite = true;

    // Successfully opened the file.
    myStatus = SamStatus::SUCCESS;
    return(true);
}

bool SamFile::ReadBamIndex

(

const char *

filename

)

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.

Returns:

true = success; false = failure.

Definition at line 298 of file SamFile.cpp.

References myStatus, and BamIndex::readIndex().

{
    // Cleanup a previously setup index.
    if(myBamIndex != NULL)
    {
        delete myBamIndex;
        myBamIndex = NULL;
    }

    // Create a new bam index.
    myBamIndex = new BamIndex();
    SamStatus::Status indexStat = myBamIndex->readIndex(bamIndexFilename);

    if(indexStat != SamStatus::SUCCESS)
    {
        std::string errorMessage = "Failed to read the bam Index file: ";
        errorMessage += bamIndexFilename;
        myStatus.setStatus(indexStat, errorMessage.c_str());
        delete myBamIndex;
        myBamIndex = NULL;
        return(false);
    }
    myStatus = SamStatus::SUCCESS;
    return(true);
}

bool SamFile::ReadHeader

(

SamFileHeader &

header

)

Reads the header section from the file and stores it in the passed in header.

Returns:

true = success; false = failure.

Definition at line 369 of file SamFile.cpp.

References myHasHeader, myIsOpenForRead, and myStatus.

{
    if(myIsOpenForRead == false)
    {
        // File is not open for read
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Cannot read header since the file is not open for reading");
        return(false);
    }

    if(myHasHeader == true)
    {
        // The header has already been read.
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Cannot read header since it has already been read.");
        return(false);
    }

    myStatus = myInterfacePtr->readHeader(myFilePtr, header);
    if(myStatus == SamStatus::SUCCESS)
    {
        // The header has now been successfully read.
        myHasHeader = true;
        return(true);
    }
    return(false);
}

bool SamFile::ReadRecord	(	SamFileHeader &	header,
		SamRecord &	record
	)

Reads the next record from the file & stores it in the passed in record.

Returns:

true = record was successfully set. false = record was not successfully set.

Definition at line 433 of file SamFile.cpp.

References myHasHeader, myIsOpenForRead, myRecordCount, myStatistics, myStatus, readIndexedRecord(), BamIndex::REF_ID_ALL, SamRecord::setReference(), SamRecord::setSequenceTranslation(), and validateSortOrder().

{
    myStatus = SamStatus::SUCCESS;

    if(myIsOpenForRead == false)
    {
        // File is not open for read
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Cannot read record since the file is not open for reading");
        throw(std::runtime_error("SOFTWARE BUG: trying to read a SAM/BAM record prior to opening the file."));
        return(false);
    }

    if(myHasHeader == false)
    {
        // The header has not yet been read.
        // TODO - maybe just read the header.
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Cannot read record since the header has not been read.");
        throw(std::runtime_error("SOFTWARE BUG: trying to read a SAM/BAM record prior to reading the header."));
        return(false);
    }

    // Check to see if a new region has been set.  If so, determine the
    // chunks for that region.
    if(myNewSection)
    {
        if(!processNewSection(header))
        {
            // Failed processing a new section.  Could be an 
            // order issue like the file not being open or the
            // indexed file not having been read.
            // processNewSection sets myStatus with the failure reason.
            return(false);
        }
    }

    // Check to see if the file should be read by index.
    if(myRefID != BamIndex::REF_ID_ALL)
    {
        // Reference ID is set, so read by index.
        return(readIndexedRecord(header, record));
    }

    record.setReference(myRefPtr);
    record.setSequenceTranslation(myReadTranslation);

    // File is open for reading and the header has been read, so read the next
    // record.
    myInterfacePtr->readRecord(myFilePtr, header, record, myStatus);
    if(myStatus == SamStatus::SUCCESS)
    {
        // A record was successfully read, so increment the record count.
        myRecordCount++;

        if(myStatistics != NULL)
        {
            // Statistics should be updated.
            myStatistics->updateStatistics(record);
        }

        // Successfully read the record, so check the sort order.
        if(!validateSortOrder(record, header))
        {
            // ValidateSortOrder sets the status on a failure.
            return(false);
        }
        return(true);
    }
    // Failed to read the record.
    return(false);
}

bool SamFile::SetReadSection	(	const char *	refName,
		int32_t	start,
		int32_t	end
	)

Sets what part of the BAM file should be read.

This version will set it to only read a specific reference name and start/end position. The records for this section will be retrieved on each ReadRecord call. When all records have been retrieved for the specified section, ReadRecord will return failure until a new read section is set. Must be called only after the file has been opened for reading.

Parameters:

	refName	the reference name of the records to read from the file.
	start	inclusive 0-based start position of records that should be read for this refID.
	end	exclusive 0-based end position of records that should be read for this refID.

Returns:

true = success; false = failure.

Definition at line 620 of file SamFile.cpp.

References myIsBamOpenForRead, myStatus, BamIndex::REF_ID_ALL, and BamIndex::REF_ID_UNMAPPED.

{
    // If there is not a BAM file open for reading, return failure.
    // Opening a new file clears the read section, so it must be
    // set after the file is opened.
    if(!myIsBamOpenForRead)
    {
        // There is not a BAM file open for reading.
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Canot set section since there is no bam file open");
        return(false);
    }

    myNewSection = true;
    myStartPos = start;
    myEndPos = end;
    if((strcmp(refName, "") == 0) || (strcmp(refName, "*") == 0))
    {
        // No Reference name specified, so read just the "-1" entries.
        myRefID = BamIndex::REF_ID_UNMAPPED;
    }
    else
    {
        // save the reference name and revert the reference ID to unknown
        // so it will be calculated later.
        myRefName = refName;
        myRefID = BamIndex::REF_ID_ALL;
    }
    myChunksToRead.clear();
    // Reset the end of the current chunk.  We are resetting our read, so
    // we no longer have a "current chunk" that we are reading.
    myCurrentChunkEnd = 0;
    myStatus = SamStatus::SUCCESS;
    
    return(true);
}

bool SamFile::SetReadSection	(	int32_t	refID,
		int32_t	start,
		int32_t	end
	)

Sets what part of the BAM file should be read.

This version will set it to only read a specific reference id and start/end position. The records for this section will be retrieved on each ReadRecord call. When all records have been retrieved for the specified section, ReadRecord will return failure until a new read section is set. Must be called only after the file has been opened for reading.

Parameters:

	refID	the reference ID of the records to read from the file.
	start	inclusive 0-based start position of records that should be read for this refID.
	end	exclusive 0-based end position of records that should be read for this refID.

Returns:

true = success; false = failure.

Definition at line 591 of file SamFile.cpp.

References myIsBamOpenForRead, and myStatus.

{
    // If there is not a BAM file open for reading, return failure.
    // Opening a new file clears the read section, so it must be
    // set after the file is opened.
    if(!myIsBamOpenForRead)
    {
        // There is not a BAM file open for reading.
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Canot set section since there is no bam file open");
        return(false);
    }

    myNewSection = true;
    myStartPos = start;
    myEndPos = end;
    myRefID = refID;
    myRefName.clear();
    myChunksToRead.clear();
    // Reset the end of the current chunk.  We are resetting our read, so
    // we no longer have a "current chunk" that we are reading.
    myCurrentChunkEnd = 0;
    myStatus = SamStatus::SUCCESS;
    
    return(true);
}

bool SamFile::SetReadSection

(

const char *

refName

)

Sets what part of the BAM file should be read.

This version will set it to only read a specific reference name. The records for that reference id will be retrieved on each ReadRecord call. When all records have been retrieved for the specified reference name, ReadRecord will return failure until a new read section is set. Must be called only after the file has been opened for reading.

Parameters:

refName

the reference name of the records to read from the file.

Returns:

true = success; false = failure.

Definition at line 583 of file SamFile.cpp.

References SetReadSection().

{
    // No start/end specified, so set back to default -1.
    return(SetReadSection(refName, -1, -1));
}

bool SamFile::SetReadSection

(

int32_t

refID

)

Sets what part of the BAM file should be read.

This version will set it to only read a specific reference id. The records for that reference id will be retrieved on each ReadRecord call. When all records have been retrieved for the specified reference id, ReadRecord will return failure until a new read section is set. Must be called only after the file has been opened for reading.

Parameters:

refID

the reference ID of the records to read from the file.

Returns:

true = success; false = failure.

Definition at line 574 of file SamFile.cpp.

Referenced by SetReadSection().

{
    // No start/end specified, so set back to default -1.
    return(SetReadSection(refID, -1, -1));
}

void SamFile::SetReadSequenceTranslation

(

SamRecord::SequenceTranslation

translation

)

Set the type of sequence translation to use when reading the sequence.

Passed down to the SamRecord when it is read. NONE (the sequence is left as-is).

Parameters:

translation

type of sequence translation to use.

Definition at line 333 of file SamFile.cpp.

{
    myReadTranslation = translation;
}

void SamFile::SetReference

(

GenomeSequence *

reference

)

Sets the reference to the specified genome sequence object.

Parameters:

reference

pointer to the GenomeSequence object.

Definition at line 326 of file SamFile.cpp.

{
    myRefPtr = reference;
}

void SamFile::setSortedValidation

(

SortedType

sortType

)

Set the flag to validate that the file is sorted as it is read/written.

Must be called after the file has been opened.

Definition at line 560 of file SamFile.cpp.

{
    mySortedType = sortType;
}

void SamFile::SetWriteSequenceTranslation

(

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).

Parameters:

translation

type of sequence translation to use.

Definition at line 340 of file SamFile.cpp.

{
    myWriteTranslation = translation;
}

bool SamFile::validateSortOrder	(	SamRecord &	record,
		SamFileHeader &	header
	)			[protected]

Validate that the record is sorted compared to the previously read record if there is one, according to the specified sort order.

If the sort order is UNSORTED, true is returned.

Definition at line 752 of file SamFile.cpp.

References FLAG, SamRecord::get0BasedPosition(), SamRecord::getReadName(), SamRecord::getReferenceID(), myPrevCoord, myRecordCount, myStatus, QUERY_NAME, BamIndex::REF_ID_UNMAPPED, SamRecord::setReference(), SamRecord::setSequenceTranslation(), and UNSORTED.

Referenced by readIndexedRecord(), ReadRecord(), and WriteRecord().

{
    if(myRefPtr != NULL)
    {
        record.setReference(myRefPtr);
    }
    record.setSequenceTranslation(myReadTranslation);

    bool status = false;
    if(mySortedType == UNSORTED)
    {
        // Unsorted, so nothing to validate, just return true.
        status = true;
    }
    else 
    {
        // Check to see if mySortedType is based on the header.
        if(mySortedType == FLAG)
        {
            // Determine the sorted type from what was read out of the header.
            mySortedType = getSortOrderFromHeader(header);
        }

        if(mySortedType == QUERY_NAME)
        {
            // Validate that it is sorted by query name.
            // Get the query name from the record.
            const char* readName = record.getReadName();
            if(myPrevReadName.compare(readName) > 0)
            {
                // The previous name is greater than the new record's name, so
                // return false.
                String errorMessage = "ERROR: File is not sorted at record ";
                errorMessage += myRecordCount;
                myStatus.setStatus(SamStatus::INVALID_SORT, 
                                   errorMessage.c_str());
                status = false;
            }
            else
            {
                myPrevReadName = readName;
                status = true;
            }
        }
        else 
        {
            // Validate that it is sorted by COORDINATES.
            // Get the leftmost coordinate and the reference index.
            int32_t refID = record.getReferenceID();
            int32_t coord = record.get0BasedPosition();
            // The unmapped reference id is at the end of a sorted file.
            if(refID == BamIndex::REF_ID_UNMAPPED)
            {
                // A new reference ID that is for the unmapped reads
                // is always valid.
                status = true;
                myPrevRefID = refID;
                myPrevCoord = coord;
            }
            else if(myPrevRefID == BamIndex::REF_ID_UNMAPPED)
            {
                // Previous reference ID was for unmapped reads, but the
                // current one is not, so this is not sorted.
                String errorMessage = "ERROR: File is not sorted at record ";
                errorMessage += myRecordCount;
                myStatus.setStatus(SamStatus::INVALID_SORT, 
                                   errorMessage.c_str());
                status = false;
            }
            else if(refID < myPrevRefID)
            {
                // Current reference id is less than the previous one, 
                //meaning that it is not sorted.
                String errorMessage = "ERROR: File is not sorted at record ";
                errorMessage += myRecordCount;
                myStatus.setStatus(SamStatus::INVALID_SORT, 
                                   errorMessage.c_str());
                status = false;
            }
            else
            {
                // The reference IDs are in the correct order.
                if(refID > myPrevRefID)
                {
                    // New reference id, so set the previous coordinate to -1
                    myPrevCoord = -1;
                }
            
                // Check the coordinates.
                if(coord < myPrevCoord)
                {
                    // New Coord is less than the previous position.
                    String errorMessage = "ERROR: File is not sorted at record ";
                    errorMessage += myRecordCount;
                    myStatus.setStatus(SamStatus::INVALID_SORT, 
                                       errorMessage.c_str());
                    status = false;
                }
                else
                {
                    myPrevRefID = refID;
                    myPrevCoord = coord;
                    status = true;
                }
            }
        }
    }

    return(status);
}

bool SamFile::WriteHeader

(

SamFileHeader &

header

)

Writes the specified header into the file.

Returns:

true = success; false = failure.

Definition at line 399 of file SamFile.cpp.

References myHasHeader, myIsOpenForWrite, and myStatus.

{
    if(myIsOpenForWrite == false)
    {
        // File is not open for write
        // -OR-
        // The header has already been written.
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Cannot write header since the file is not open for writing");
        return(false);
    }

    if(myHasHeader == true)
    {
        // The header has already been written.
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Cannot write header since it has already been written");
        return(false);
    }

    myStatus = myInterfacePtr->writeHeader(myFilePtr, header);
    if(myStatus == SamStatus::SUCCESS)
    {
        // The header has now been successfully written.
        myHasHeader = true;
        return(true);
    }

    // return the status.
    return(false);
}

bool SamFile::WriteRecord	(	SamFileHeader &	header,
		SamRecord &	record
	)

Writes the specified record into the file.

Returns:

true = success; false = failure.

Definition at line 510 of file SamFile.cpp.

References myHasHeader, myIsOpenForWrite, myRecordCount, myStatus, SamRecord::setReference(), and validateSortOrder().

{
    if(myIsOpenForWrite == false)
    {
        // File is not open for writing
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Cannot write record since the file is not open for writing");
        return(false);
    }

    if(myHasHeader == false)
    {
        // The header has not yet been written.
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Cannot write record since the header has not been written");
        return(false);
    }

    // Before trying to write the record, validate the sort order.
    if(!validateSortOrder(record, header))
    {
        // Not sorted like it is supposed to be, do not write the record
        myStatus.setStatus(SamStatus::INVALID_SORT, 
                           "Cannot write the record since the file is not properly sorted.");
        return(false);
    }

    if(myRefPtr != NULL)
    {
        record.setReference(myRefPtr);
    }

    // File is open for writing and the header has been written, so write the
    // record.
    myStatus = myInterfacePtr->writeRecord(myFilePtr, header, record,
                                           myWriteTranslation);

    if(myStatus == SamStatus::SUCCESS)
    {
        // A record was successfully written, so increment the record count.
        myRecordCount++;
        return(true);
    }
    return(false);
}

---

Member Data Documentation

bool SamFile::myHasHeader [protected]

Flag to indicate if a header has been read/written - required before being able to read/write a record.

Definition at line 240 of file SamFile.h.

Referenced by ReadHeader(), ReadRecord(), resetFile(), WriteHeader(), and WriteRecord().

---

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

• lib/bam/SamFile.h
• lib/bam/SamFile.cpp