FaiIndex - SeqAn API Documentation

# Class FaiIndex
Data structure for access to FAI indices.

Defined in | <seqan/seq_io.h>
Signature | `class FaiIndex;`

## Member Function Overview

- `FaiIndex::FaiIndex();`
  Constructor.

## Interface Function Overview

- `bool build(faiIndex, fastaFilename[, faiFileName]);`
  Create a FaiIndex from FASTA file.
- `void clear(faiIndex);`
  Reset a FaiIndex object to the state after default construction.
- `void empty(faiIndex);`
  Returns whether the FaiIndex is empty.
- `bool getIdByName(rID, faiIndex, name);`
  Return reference ID (numeric index in the file) of a sequence in a FAI file.
- `uint64_t numSeqs(faiIndex);`
  Return the number of sequences known to a FaiIndex.
- `bool open(faiIndex, fastaFilename [, faiFileName]);`
  Open a FaiIndex object.
- `void readRecord(faiIndex, fastaFileName[, faiFileName]);`
  Read a FAI index from file.
- `void readRegion(str, faiIndex, rID, beginPos, endPos);, void readRegion(str, faiIndex, region);`
  Read a region through an FaiIndex.
- `void readSequence(str, faiIndex, rID);`
  Load a whole sequence from a FaiIndex.
- `bool save(faiIndex[, faiFileName]);`
  Save a FaiIndex object.
- `uint64_t sequenceLength(faiIndex, rID);`
  Return length of the sequence with the given id in the FaiIndex.
- `CharString sequenceName(faiIndex, rID);`
  Return the name of the sequence with the given id in the FaiIndex.

## Detailed Description

FAI indices allow the rast random access to sequences or parts of sequences in a FASTA file. Originally, they were introduced in the samtools program.

Also see the Indexed FASTA I/O Tutorial.

### Example

The following example demonstrates the usage of the FaiIndex class.

    #include <seqan/basic.h>
    #include <seqan/seq_io.h>
    #include <seqan/sequence.h>

    using namespace seqan;

    int main()
    {
        CharString path = getAbsolutePath("demos/dox/seq_io/example.fa");

        FaiIndex faiIndex;

        // Try to read the FAI index.
        if (!open(faiIndex, toCString(path)))
        {
            std::cerr << "Could not read the FAI index.  Not fatal, we can just build it.\n";
            return 1;
        }

        // Try to build the FAI index (in memory) if reading was unsuccessful.  If
        // building into memory succeeded, we try to write it out.
        if (!build(faiIndex, toCString(path)))
        {
            std::cerr << "FATAL: Could not build FAI index.\n";
            return 1;
        }

        if (!save(faiIndex))
        {
            std::cerr << "FATAL: Could not write out FAI index after building.\n";
            return 1;
        }

        // Now, read the first 1000 characters of chr1.
        unsigned idx = 0;
        if (!getIdByName(idx, faiIndex, "chr"))
        {
            std::cerr << "FATAL: chr1 not found in FAI index.\n";
            return 1;
        }
        CharString seq;
        readRegion(seq, faiIndex, idx, 0, 100);

        // Now print the first 100 characters we just read.
        std::cout << "chr:1-100 = " << seq << "\n";

        return 0;
    }

Demo: demos/dox/seq_io/fai_index_example.cpp

The output is as follows:

    chr:1-100 = CCTATCTAATAATATACCTTATACTGGACTAGTGCCAATATTAAAATGAAGTGGGCGTAGTGTGTAATTTGATTGGGTGGAGGTGTGGCTTTGGCGTGCT

## Member Functions Detail

### `FaiIndex::FaiIndex();`

Constructor.

#### Data Races

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

## Interface Functions Detail

### `bool build(faiIndex, fastaFilename[, faiFileName]);`

Create a FaiIndex from FASTA file.

#### Parameters

`faiIndex` | The FaiIndex to build into.
`fastaFilename` | Path to the FASTA file to build an index for. Type: `char const *`.
`faiFileName` | Path to the FAI file to use as the index file. Type: `char const *`. Default: `"${fastaFilename}.fai"`.

#### Returns

`bool` | `true` on success, `false` otherwise.

#### Data Races

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

### `void clear(faiIndex);`

Reset a FaiIndex object to the state after default construction.

#### Parameters

`faiIndex` | The FaiIndex to clear.

#### Data Races

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

### `void empty(faiIndex);`

Returns whether the FaiIndex is empty.

#### Parameters

`faiIndex` | The FaiIndex to check.

#### Returns

`bool` | `true` if the index is empty and needs to be built via build.

#### Data Races

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

### `bool getIdByName(rID, faiIndex, name);`

Return reference ID (numeric index in the file) of a sequence in a FAI file.

#### Parameters

`faiIndex` | The FaiIndex to query.
`name` | The name of the sequence to look the id up for. Type: ContainerConcept.
`rID` | The id of the sequence is written here.

#### Returns

`bool` | `true` if a sequence with the given name is known in the index, `false` otherwise.

#### Data Races

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

### `uint64_t numSeqs(faiIndex);`

Return the number of sequences known to a FaiIndex.

#### Parameters

`faiIndex` | The FaiIndex to query.

#### Returns

`uint64_t` | The number of sequences in the index.

#### Data Races

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

### `bool open(faiIndex, fastaFilename [, faiFileName]);`

Open a FaiIndex object.

#### Parameters

`faiIndex` | The FaiIndex to write out.
`fastaFilename` | Path to the FASTA file to build an index for. Type: `char const *`.
`faiFileName` | The name of the FAI file to open. This parameter is optional. By default, the FAI file name is derived from the FASTA file name. Type: `char const *`.

#### Returns

`bool` | `true` on success, `false` otherwise.

#### Data Races

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

### `void readRecord(faiIndex, fastaFileName[, faiFileName]);`

Read a FAI index from file.

#### Parameters

`faiIndex` | The FaiIndex to read into.
`fastaFileName` | Path to the FASTA file to read. Type: `char const *`.
`faiFileName` | Path to the FAI file to read. Type: `char const *`. Defaults to `"${fastaFileName}.fai"`.

#### Data Races

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

### `void readRegion(str, faiIndex, rID, beginPos, endPos); void readRegion(str, faiIndex, region);`

Read a region through an FaiIndex.

#### Parameters

`str` | The String to read the sequence into.
`faiIndex` | The FaiIndex to read from.
`rID` | The id of the sequence to read (Type: `unsigned).`
`beginPos` | The begin position of the region to read (Type: `unsigned).`
`endPos` | The end position of the region to read (Type: `unsigned).`
`region` | The GenomicRegion to read.

#### Data Races

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

### `void readSequence(str, faiIndex, rID);`

Load a whole sequence from a FaiIndex.

#### Parameters

`str` | The String to read into.
`faiIndex` | The FaiIndex to read from.
`seqID` | The index of the sequence in the file.

#### Data Races

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

### `bool save(faiIndex[, faiFileName]);`

Save a FaiIndex object.

#### Parameters

`faiIndex` | The FaiIndex to write out.
`faiFileName` | The name of the FAI file to write to. This parameter is optional only if the FAI index knows the FAI file name from a previous build call. By default, the FAI file name from the previous call to build is used. Type: `char const *`.

#### Returns

`bool` | `true` on success, `false` otherwise.

#### Data Races

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

### `uint64_t sequenceLength(faiIndex, rID);`

Return length of the sequence with the given id in the FaiIndex.

#### Parameters

`faiIndex` | The FaiIndex to query.
`rID` | The id of the sequence to get the length of.

#### Returns

`uint64_t` | The length of the sequence with index rID in faiIndex.

#### Data Races

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

### `CharString sequenceName(faiIndex, rID);`

Return the name of the sequence with the given id in the FaiIndex.

#### Parameters

`faiIndex` | The FaiIndex to query.
`rID` | The index of the sequence.

#### Returns

`CharString` | The name of the sequence with the given id.

#### Data Races

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

#### Dox Sources

    /*!
     * @class FaiIndex
     *
     * @headerfile <seqan/seq_io.h>
     *
     * @brief Data structure for access to FAI indices.
     *
     * @signature class FaiIndex;
     *
     * FAI indices allow the rast random access to sequences or parts of sequences
     * in a FASTA file. Originally, they were introduced in the <a
     * href="http://samtools.sourceforge.net/samtools.shtml">samtools</a> program.
     *
     * Also see the <a href="http://seqan.readthedocs.io/en/develop/Tutorial/InputOu
     * tput/IndexedFastaIO.html">Indexed FASTA I/O Tutorial</a>.
     *
     * @section Example
     *
     * The following example demonstrates the usage of the FaiIndex class.
     *
     * @include demos/dox/seq_io/fai_index_example.cpp
     *
     * The output is as follows:
     *
     * @include demos/dox/seq_io/fai_index_example.cpp.stdout
     *
     * @fn FaiIndex::FaiIndex
     *
     * @brief Constructor.
     *
     * @signature FaiIndex::FaiIndex();
     *
     * @fn FaiIndex#clear
     *
     * @brief Reset a FaiIndex object to the state after default construction.
     *
     * @signature void clear(faiIndex);
     *
     * @param[in,out] faiIndex The FaiIndex to clear.
     *
     * @fn FaiIndex#empty
     *
     * @brief Returns whether the FaiIndex is empty.
     *
     * @signature void empty(faiIndex);
     *
     * @param[in] faiIndex The FaiIndex to check.
     *
     * @return bool <tt>true</tt> if the index is empty and needs to be built via
     *              @link FaiIndex#build @endlink.
     *
     * @fn FaiIndex#getIdByName
     *
     * @brief Return reference ID (numeric index in the file) of a sequence in a FAI
     *        file.
     *
     * @signature bool getIdByName(rID, faiIndex, name);
     *
     * @param[in] faiIndex The FaiIndex to query.
     * @param[in] name The name of the sequence to look the id up for. Type: @link
     *                 ContainerConcept @endlink.
     * @param[out] rID The id of the sequence is written here.
     *
     * @return bool <tt>true</tt> if a sequence with the given name is known in the
     *              index, <tt>false</tt> otherwise.
     *
     * @fn FaiIndex#sequenceLength
     *
     * @brief Return length of the sequence with the given id in the FaiIndex.
     *
     * @signature uint64_t sequenceLength(faiIndex, rID);
     *
     * @param[in] faiIndex The FaiIndex to query.
     * @param[in] rID The id of the sequence to get the length of.
     *
     * @return uint64_t The length of the sequence with index rID in faiIndex.
     *
     * @fn FaiIndex#sequenceName
     *
     * @brief Return the name of the sequence with the given id in the FaiIndex.
     *
     * @signature CharString sequenceName(faiIndex, rID);
     *
     * @param[in] faiIndex The FaiIndex to query.
     * @param[in] rID The index of the sequence.
     *
     * @return CharString The name of the sequence with the given id.
     *
     * @fn FaiIndex#numSeqs
     *
     * @brief Return the number of sequences known to a FaiIndex.
     *
     * @signature uint64_t numSeqs(faiIndex);
     *
     * @param[in] faiIndex The FaiIndex to query.
     *
     * @return uint64_t The number of sequences in the index.
     *
     * @fn FaiIndex#readRegion
     *
     * @brief Read a region through an FaiIndex.
     *
     * @signature void readRegion(str, faiIndex, rID, beginPos, endPos);
     * @signature void readRegion(str, faiIndex, region);
     *
     * @param[out] str The @link String @endlink to read the sequence into.
     * @param[in] faiIndex The FaiIndex to read from.
     * @param[in] rID The id of the sequence to read (Type: <tt>unsigned).
     * @param[in] beginPos The begin position of the region to read (Type:
     *                     <tt>unsigned).
     * @param[in] endPos The end position of the region to read (Type:
     *                   <tt>unsigned).
     * @param[in] region The @link GenomicRegion @endlink to read.
     *
     * @fn FaiIndex#readSequence
     *
     * @brief Load a whole sequence from a FaiIndex.
     *
     * @signature void readSequence(str, faiIndex, rID);
     *
     * @param[out] str The @link String @endlink to read into.
     * @param[in] faiIndex The FaiIndex to read from.
     * @param[in] seqID The index of the sequence in the file.
     *
     * @fn FaiIndex#readRecord
     *
     * @brief Read a FAI index from file.
     *
     * @signature void readRecord(faiIndex, fastaFileName[, faiFileName]);
     *
     * @param[out] faiIndex The FaiIndex to read into.
     * @param[in] fastaFileName Path to the FASTA file to read. Type: <tt>char const
     *                          *</tt>.
     * @param[in] faiFileName Path to the FAI file to read. Type: <tt>char const
     *                        *</tt>. Defaults to <tt>"${fastaFileName}.fai"</tt>.
     *
     * @fn FaiIndex#open
     *
     * @brief Open a FaiIndex object.
     *
     * @signature bool open(faiIndex, fastaFilename [, faiFileName]);
     *
     * @param[in] faiIndex The FaiIndex to write out.
     * @param[in] fastaFilename Path to the FASTA file to build an index for. Type:
     *                          <tt>char const *</tt>.
     * @param[in] faiFileName The name of the FAI file to open. This parameter is
     *                        optional. By default, the FAI file name is derived
     *                        from the FASTA file name. Type: <tt>char const *</tt>.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> otherwise.
     *
     * @fn FaiIndex#save
     *
     * @brief Save a FaiIndex object.
     *
     * @signature bool save(faiIndex[, faiFileName]);
     *
     * @param[in] faiIndex The FaiIndex to write out.
     * @param[in] faiFileName The name of the FAI file to write to. This parameter
     *                        is optional only if the FAI index knows the FAI file
     *                        name from a previous @link FaiIndex#build @endlink
     *                        call. By default, the FAI file name from the previous
     *                        call to @link FaiIndex#build @endlink is used. Type:
     *                        <tt>char const *</tt>.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> otherwise.
     *
     * @fn FaiIndex#build
     *
     * @brief Create a FaiIndex from FASTA file.
     *
     * @signature bool build(faiIndex, fastaFilename[, faiFileName]);
     *
     * @param[out] faiIndex The FaiIndex to build into.
     * @param[in] fastaFilename Path to the FASTA file to build an index for. Type:
     *                          <tt>char const *</tt>.
     * @param[in] faiFileName Path to the FAI file to use as the index file. Type:
     *                        <tt>char const *</tt>. Default:
     *                        <tt>"${fastaFilename}.fai"</tt>.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> otherwise.
     */