Spec BamFileIn
Class for reading SAM and BAM files.

Extends FormattedFileIn
All Extended FormattedFile, FormattedFileIn
Defined in <seqan/bam_io.h>
Signature typedef FormattedFile<Bam, Input> BamFileIn;

Member Function Overview

Member Functions Inherited From FormattedFile

Interface Function Overview

Interface Functions Inherited From FormattedFile

Interface Functions Inherited From FormattedFileIn

Interface Metafunction Overview

Interface Metafunctions Inherited From FormattedFile

Detailed Description

Example

Access SAM or BAM files.

#include <seqan/bam_io.h>

using namespace seqan2;

int main()
{
    CharString bamFileName = getAbsolutePath("demos/tutorial/sam_and_bam_io/example.sam");

    // Open input file, BamFileIn can read SAM and BAM files.
    BamFileIn bamFileIn;
    if (!open(bamFileIn, toCString(bamFileName)))
    {
        std::cerr << "ERROR: Could not open " << bamFileName << std::endl;
        return 1;
    }
    // Open output file, BamFileOut accepts also an ostream and a format tag.
    BamFileOut bamFileOut(context(bamFileIn), std::cout, Sam());

    try
    {
        // Copy header.
        BamHeader header;
        readHeader(header, bamFileIn);
        writeHeader(bamFileOut, header);

        // Copy records.
        BamAlignmentRecord record;
        while (!atEnd(bamFileIn))
        {
            readRecord(record, bamFileIn);
            writeRecord(bamFileOut, record);
        }
    }
    catch (Exception const & e)
    {
        std::cout << "ERROR: " << e.what() << std::endl;
        return 1;
    }

    return 0;
}
Demo: demos/tutorial/sam_and_bam_io/solution1.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

Interface Functions Detail

bool jumpToOrphans(bamFileIn, hasAlignments, index);

Seek to orphans block in BamFileIn using an index.

Parameters

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

Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

bool jumpToRegion(bamFileIn, hasAlignments, refID, regionStart, regionEnd, index);

Seek in BamFileIn using an index.

Parameters

bamFileIn The BamFileIn to jump with.
hasAlignments A bool that is set true if the region [regionStart, regionEnd] has any at least one overlapping alignment (bam record).
refID The reference id to jump to (int32_t).
regionStart The begin of the region to jump to (int32_t).
regionEnd The end of the region to jump to (int32_t).
index The BamIndex to use for the jumping.

Returns

bool `false` if an error occurred while seeking, otherwise `true`.

You provide a 1-based region [regionStart, regionEnd] on the reference refID that you want to jump to and the function jumps to the first alignment (bam record) whose **start position** lies inside this region, if any.

Note: The current implementation only considers the read start positions. Therefore, we do guarantee that reads overlapping the region are included. To account for this limitation you may want to choose the start of your your region with an appropriate offset (e.g. start - length_of_read) or use viewRecords().

Remarks

This function fails if refID/regionStart are invalid.

Thrown Exceptions

ParseError when reading the bamFile or index fails.
std::logical_error when the input arguments are invalid.

Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

bool viewRecords(resultContainer, bamFileIn, bamIndex, refID, regionStart, regionEnd, index);

Extract all reads overlapping a region from a BamFileIn mimicking samtools view.

Parameters

resultContainer Container of BamAlignmentRecord 's to store the alignments.
bamFileIn The BamFileIn to extract reads from.
bamIndex The BamIndex over the `bamFileIn`.
refID The reference id to extract reads from (int32_t).
regionStart The begin of the region to extract reads from (int32_t).
regionEnd The end of the region to extract reads from (int32_t).

You provide a 1-based region [regionStart, regionEnd] on the reference refID and the functions extracts all reads that overlap this region with at least one base. The overlapping records are **appended** in the resultContainer, which must be a container over BamAlignmentRecord. This function extracts the same records as samtools view would do when the same region is specified. The result container remains empty if an error occurred or no reads were found.

Remarks This function fails if refID/regionStart are invalid.

Thrown Exceptions

ParseError when reading the bamFile or index fails.
std::logical_error when the input arguments are invalid.

Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.