Class BamStream
Class that provides an easy to use interface for reading and writing SAM and BAM files.

Defined in <seqan/bam_io.h>
Signature class BamStream;

Member Function Overview

Interface Function Overview

Member Variable Overview

Detailed Description

Example

Read and write SAM or BAM files.

#include <iostream>
#include <seqan/file.h>
#include <seqan/bam_io.h>

using namespace seqan;

int main()
{
    // Open input stream, BamStream can read SAM and BAM files.
    std::string pathSam = std::string(SEQAN_PATH_TO_ROOT()) + "/core/demos/bam_io/example.sam";
   
    BamStream bamStreamIn(pathSam.c_str());
    if (!isGood(bamStreamIn))
    {
        std::cerr << "Can't open the file." << std::endl;
        return 1;
    }
    
    // Open output stream. The value "-" means reading from stdin or writing to stdout.
    BamStream bamStreamOut("-", BamStream::WRITE);
    // Copy header. The header is automatically written out before the first record.
    bamStreamOut.header = bamStreamIn.header;

    // BamAlignmentRecord stores one record at a time.
    BamAlignmentRecord record;
    while (!atEnd(bamStreamIn))
    {
        if (readRecord(record, bamStreamIn) != 0)
        {
            std::cerr << "Can't read record!" << std::endl;
            return 1;
        }
        if (writeRecord(bamStreamOut, record) != 0)
        {
            std::cout << "Can't write record!" << std::endl;
            return 1;
        }
    }
    return 0;
}
Demo: demos/bam_io/bam_stream.cpp

The output is as follows:

@HD	VN:1.3	SO:coordinate
@SQ	SN:ref	LN:45
@SQ	SN:ref2	LN:40
r001	163	ref	7	30	8M4I4M1D3M	=	37	39	TTAGATAAAGAGGATACTG	*	XX:B:S,12561,2,20,112
r002	0	ref	9	30	1S2I6M1P1I1P1I4M2I	*	0	0	AAAAGATAAGGGATAAA	*
r003	0	ref	9	30	5H6M	*	0	0	AGCTAA	*
r004	0	ref	16	30	6M14N1I5M	*	0	0	ATAGCTCTCAGC	*
r003	16	ref	29	30	6H5M	*	0	0	TAGGC	*
r001	83	ref	37	30	9M	=	7	-39	CAGCGCCAT	*

See Also

Member Functions Detail

BamStream::BamStream([fileName[, mode[, format]]]);

Constructor

Parameters

fileName The path to the SAM or BAM file to load, char const *.
mode The open mode, of type BamStream::OperationMode, defaults to READ.
format The format, of type BamStream::Format, defaults to AUTO.

Interface Functions Detail

bool atEnd(stream);

Check whether a BamStream object is at end when reading.

Parameters

stream The BamStream object to query.

Returns

bool true in case of the stream being at the end, false otherwise.

Remarks

The stream will only be guaranteed at the end after trying to read after the last character.

int close(stream);

Close BamStream object's underlying file.

Parameters

stream The BamStream object to close.

Returns

int A status code, 0 on success, != 0 on error.

__int64 fileSize(stream);

Returns the size of the file in bytes as stored on the disk.

Parameters

stream The BamStream to query.

Returns

__int64 The size of the file on the disk.

Remarks

This only works when reading.

int flush(stream);

Flush output when writing.

Parameters

stream The BamStream object to flush.

Returns

int A status code, 0 on success, != 0 on errors.

Remarks

This will write out the header if no record has been written out yet.

bool isGood(stream);

Check whether the BamStream object has is in the failure state.

Parameters

stream The BamStream object to query.

Returns

bool true if the stream is not in an error state and false otherwise.

bool jumpToOrphans(stream, hasAlignments, index);

Seek to orphans block in BamStream using an index.

Parameters

stream The BgzfStream object to jump with.
hasAlignments A bool that is set to true if there are any orphans.
index The index to use for jumping.

See Also

bool jumpToRegion(stream, hasAlignments, bamIOContext, refID, pos, posEnd, index);

Seek in BamStream using an index.

Parameters

stream The BamStream to jump with.
hasAlignments A bool that is set true if the region [pos, posEnd) has any alignments.
refID The reference id to jump to (__int32).
pos The begin of the region to jump to (__int32).
posEnd The end of the region to jump to (__int32).
index The BamIndex to use for the jumping.

Returns

bool true if seeking was successful, false if not.

You provide a region [pos, posEnd) on the reference refID that you want to jump to and the function jumps to the first alignment in this region, if any.

Remarks

This function fails if refID/pos are invalid.

See Also

int open(bamIO, fileName[, mode[, format]]);

Open a BamStream object for reading/writing.

Parameters

bamIO The BamStream object to open. Types: BamStream
fileName The path to the file to open, char const *.
mode The mode to open the file in, optional, of type BamStream::OperationMode, defaults to BamStream::READ.
format The format to use, inferred from file contents (reading) or file name (writing) by default. the path to the file to open, of type BamStream::Format, defaults to AUTO.

Returns

int A status code, 0 on success, a value != 0 on errors.

__int64 positionInFile(stream);

Approximate byte position in file, to be used for progress display, not for seeking.

Parameters

stream The BamStream to query for its position in the file.

Returns

__int64 The position in the file.

Remarks

This function returns the "approximate" position in the file and only works when the file is opened in BAM format. It is meant for progress display in connection with fileSize and not for jumping within the file. The position is approximate in the sense that it points between the block boundaries of the BGZ file.

int readRecord(record, stream);

Read one BamAlignmentRecord from a BamStream.

Parameters

record The BamAlignmentRecord to read the next alignment record into. Of type BamAlignmentRecord.
stream The BamStream object to read from.

Returns

int A status code, 0 on success.

int writeRecord(stream, record);

Write one BamAlignmentRecord to a BamStream.

Parameters

bamIO The BamStream object to write to.
record The BamAlignmentRecord to write out.

Returns

int A status code, 0 on success.

Member Variables Detail

TBamIOContext BamStream::bamIOContext

The BamIOContext object to use for reading and writing BamAlignmentRecords.

When reading, the bamIOContext will be updated automatically. When reading SAM, new reference sequences can be introduced "on the fly" when a new sequence appears. When writing, the bamIOContext is automatically filled/reset when the first record is written.

THeader BamStream::header

The BamHeader of the BamStream object.

SAM and BAM files have a header. When writing SAM or BAM files, you have to fill this member before writing BamAlignmentRecords. Upon writing the first record, the header will be written out.

When reading BAM files, the header will be read upon opening the file. When reading SAM files, any header will be read upon opening the file.

Note that there is a special case when reading SAM records: If there is no header, or records refer to reference sequences that are previously unknown when reading SAM then a new entry is added to sequenceInfos.