# 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

- `getFileExtensions`
- `operatorTDependentContext`

## Interface Function Overview

- `bool jumpToOrphans(bamFileIn, hasAlignments, index);`
  Seek to orphans block in BamFileIn using an index.
- `bool jumpToRegion(bamFileIn, hasAlignments, refID, regionStart, regionEnd, index);`
  Seek in BamFileIn using an index.

### Interface Functions Inherited From FormattedFile

- `atEnd`
- `close`
- `context`
- `format`
- `FormattedFile`
- `getFileExtensions`
- `guessFormat`
- `isOpen`
- `open`
- `setFormat`

### Interface Functions Inherited From FormattedFileIn

- `readHeader`
- `readRecord`

## Interface Metafunction Overview

### Interface Metafunctions Inherited From FormattedFile

- `FileFormat`
- `FormattedFileContext`

## Detailed Description

### Example

Access SAM or BAM files.

    #include <seqan/bam_io.h>

    using namespace seqan;

    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

- BamAlignmentRecord
- BamHeader

## 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` | true if seeking was successful, false if not.

You provide a 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 inmplementation only consideres 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 appropiate offset (e.g. start - length_of_read).

#### Remarks

This function fails if `refID`/`regionStart` are invalid.

#### Data Races

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

#### Dox Sources

    /*!
     * @class BamFileIn
     *
     * @extends FormattedFileIn
     *
     * @headerfile <seqan/bam_io.h>
     *
     * @brief Class for reading SAM and BAM files.
     *
     * @signature typedef FormattedFile<Bam, Input> BamFileIn;
     *
     * @section Example
     *
     * Access SAM or BAM files.
     *
     * @include demos/tutorial/sam_and_bam_io/solution1.cpp
     *
     * The output is as follows:
     *
     * @include demos/tutorial/sam_and_bam_io/example.sam
     *
     *
     *
     * @see BamHeader
     * @see BamAlignmentRecord
     *
     * @fn BamFileIn#jumpToRegion
     *
     * @brief Seek in BamFileIn using an index.
     *
     * @signature bool jumpToRegion(bamFileIn, hasAlignments, refID, regionStart,
     *            regionEnd, index);
     *
     * @param[in,out] bamFileIn The @link BamFileIn @endlink to jump with.
     * @param[out] hasAlignments A <tt>bool</tt> that is set true if the region
     *                           <tt>[regionStart, regionEnd]</tt> has any at least
     *                           one overlapping alignment (bam record).
     * @param[in] refID The reference id to jump to (<tt>int32_t</tt>).
     * @param[in] regionStart The begin of the region to jump to (<tt>int32_t</tt>).
     * @param[in] regionEnd The end of the region to jump to (<tt>int32_t</tt>).
     * @param[in] index The @link BamIndex @endlink to use for the jumping.
     *
     * @return bool true if seeking was successful, false if not.
     *
     * You provide a region <tt>[regionStart, regionEnd]</tt> on the reference
     * <tt>refID</tt> 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 inmplementation only consideres 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 appropiate offset (e.g. start - length_of_read).
     *
     * @section Remarks
     *
     * This function fails if <tt>refID</tt>/<tt>regionStart</tt> are invalid.
     *
     * @fn BamFileIn#jumpToOrphans
     *
     * @brief Seek to orphans block in BamFileIn using an index.
     *
     * @signature bool jumpToOrphans(bamFileIn, hasAlignments, index);
     *
     * @param[in,out] bamFileIn The @link BamFileIn @endlink object to jump with.
     * @param[out] hasAlignments A <tt>bool</tt> that is set to true if there are
     *                           any orphans.
     * @param[in] index The @link BamIndex @endlink to use for jumping.
     */