PigeonholeFinder - SeqAn API Documentation

# Spec PigeonholeFinder
Pigeonhole-based finder. Must be used together with PigeonholePattern.

Extends | Finder
All Extended | Finder
Defined in | <seqan/index/find_pigeonhole.h>
Signature | `template <typename THaystack, typename TSpec> class Finder<THaystack, Pigeonhole<TSpec> >;`

## Template Parameters

`TSpec` | Specifies the type of pigeonhole filter.
`THaystack` | The type of the sequence that should be searched. Types: ContainerConcept

## Member Function Overview

### Member Functions Inherited From Finder

- `Finder`

## Interface Function Overview

- `THitString getWindowFindHits(finder);`
  Returns the string of hits from the finder.
- `windowFindBegin(finder, pattern, errorRate)`
  Initializes the pattern. Sets the finder on the begin position. Gets the first non-repeat range and sets it in the finder. Used together with windowFindEnd.
- `void windowFindEnd(finder, pattern);`
  Flushes the pattern. Used together with windowFindBegin and windowFindNext.
- `bool windowFindNext(finder, pattern, finderWindowLength)`
  Searches over the next window with the finder. The found hits can be retrieved with getWindowFindHits Used together with windowFindBegin and windowFindEnd.

### Interface Functions Inherited From Finder

- `begin`
- `beginPosition`
- `clear`
- `end`
- `endPosition`
- `find`
- `findBegin`
- `goBegin`
- `goEnd`
- `haystack`
- `infix`
- `length`
- `position`
- `setHaystack`
- `setPosition`

## Member Typedef Overview

- `typedef (...) PigeonholeFinder::THitString;`
  The type to use for the hit string returned in getWindowFindHits.

## Interface Metafunction Overview

### Interface Metafunctions Inherited From Finder

- `Haystack`

## Detailed Description

Provides a fast filter algorithm that uses the pigeonhole lemma, i.e. if a pattern matches with k errors in the text, every partition into k+1 parts contains one part that matches without error.

The Pattern must be a q-gram index over multiple patterns. The tolerated error rate must be given when find or windowFindBegin is called. In these functions the length of the index Shape is set automatically thus it must be modifiable at runtime, e.g. OneGappedShape.

## See Also

- PigeonholePattern

## Interface Functions Detail

### `THitString getWindowFindHits(finder);`

Returns the string of hits from the finder.

#### Parameters

`finder` | A PigeonFinder.

#### Returns

`THitString` | String of Hits, see THitString.

#### Data Races

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

#### See Also

- windowFindNext

### `windowFindBegin(finder, pattern, errorRate)`

Initializes the pattern. Sets the finder on the begin position. Gets the first non-repeat range and sets it in the finder. Used together with windowFindEnd.

#### Parameters

`finder` | The PigeonholeFinder to use.
`pattern` | The PigeonholePattern to use.
`errorRate` | Error rate that is allowed between reads and reference. Should be the same in as in windowFindNext. Types: `double`

#### Data Races

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

#### See Also

- windowFindEnd
- windowFindNext

### `void windowFindEnd(finder, pattern);`

Flushes the pattern. Used together with windowFindBegin and windowFindNext.

#### Parameters

`pattern` | A pattern with window interface.
`finder` | A finder with window interface. Types: PigeonholeFinder

#### Data Races

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

#### See Also

- windowFindBegin
- windowFindNext

### `bool windowFindNext(finder, pattern, finderWindowLength)`

Searches over the next window with the finder. The found hits can be retrieved with getWindowFindHits Used together with windowFindBegin and windowFindEnd.

#### Parameters

`finder` | The PigeonholeFinder to use.
`pattern` | The PigeonholePattern to use.
`finderWindowLength` | Number of bases that are scanned beginning from the position the finder is at. Including bases that are marked as repeats and that are skipped. Types: `unsigned`.

#### Returns

`bool` | `true`, if there are bases that can be scanned, `false` otherwise.

#### Data Races

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

#### See Also

- getWindowFindHits
- windowFindBegin
- windowFindEnd

## Member Typedef Detail

### `typedef (...) PigeonholeFinder::THitString;`

The type to use for the hit string returned in getWindowFindHits.

#### Dox Sources

    /*!
     * @class PigeonholeFinder
     *
     * @extends Finder
     *
     * @headerfile <seqan/index/find_pigeonhole.h>
     *
     * @brief Pigeonhole-based finder. Must be used together with @link
     *        PigeonholePattern @endlink.
     *
     * @signature template <typename THaystack, typename TSpec> class
     *            Finder<THaystack, Pigeonhole<TSpec> >;
     *
     * @tparam TSpec Specifies the type of pigeonhole filter.
     * @tparam THaystack The type of the sequence that should be searched. Types:
     *                   @link ContainerConcept @endlink
     *
     * Provides a fast filter algorithm that uses the pigeonhole lemma, i.e. if a
     * pattern matches with k errors in the text, every partition into k+1 parts
     * contains one part that matches without error.
     *
     * The @link Pattern @endlink must be a q-gram index over multiple patterns. The
     * tolerated error rate must be given when @link Finder#find @endlink or @link
     * PigeonholeFinder#windowFindBegin @endlink is called. In these functions the
     * length of the index @link Shape @endlink is set automatically thus it must be
     * modifiable at runtime, e.g. @link OneGappedShape @endlink.
     *
     * @see PigeonholePattern
     *
     * @typedef PigeonholeFinder::THitString
     *
     * @brief The type to use for the hit string returned in @link
     *        PigeonholeFinder#getWindowFindHits @endlink.
     *
     * @signature typedef (...) PigeonholeFinder::THitString;
     *
     * @fn PigeonholeFinder#windowFindBegin
     *
     * @headerfile <seqan/index/find_pigeonhole.h>
     *
     * @brief Initializes the pattern. Sets the finder on the begin position. Gets
     *        the first non-repeat range and sets it in the finder. Used together
     *        with @link PigeonholeFinder#windowFindEnd @endlink.
     *
     * @signature windowFindBegin(finder, pattern, errorRate)
     *
     * @param[in,out] finder The PigeonholeFinder to use.
     * @param[in,out] pattern The PigeonholePattern to use.
     * @param[in] errorRate Error rate that is allowed between reads and reference.
     *                      Should be the same in as in @link
     *                      PigeonholeFinder#windowFindNext @endlink. Types:
     *                      <tt>double</tt>
     *
     * @see PigeonholeFinder#windowFindNext
     * @see PigeonholeFinder#windowFindEnd
     *
     * @fn PigeonholeFinder#windowFindNext
     *
     * @headerfile <seqan/index/find_pigeonhol.h>
     *
     * @brief Searches over the next window with the finder. The found hits can be
     *        retrieved with @link PigeonholeFinder#getWindowFindHits @endlink Used
     *        together with @link PigeonholeFinder#windowFindBegin @endlink and
     *        @link PigeonholeFinder#windowFindEnd @endlink.
     *
     * @signature bool windowFindNext(finder, pattern, finderWindowLength)
     *
     * @param[in,out] finder The PigeonholeFinder to use.
     * @param[in,out] pattern The PigeonholePattern to use.
     * @param[in] finderWindowLength Number of bases that are scanned beginning from
     *                               the position the finder is at. Including bases
     *                               that are marked as repeats and that are
     *                               skipped. Types: <tt>unsigned</tt>.
     *
     * @return bool <tt>true</tt>, if there are bases that can be scanned,
     *              <tt>false</tt> otherwise.
     *
     * @see PigeonholeFinder#windowFindBegin
     * @see PigeonholeFinder#windowFindEnd
     * @see PigeonholeFinder#getWindowFindHits
     *
     * @fn PigeonholeFinder#windowFindEnd
     *
     * @headerfile <seqan/index/find_pigeonhole.h>
     *
     * @brief Flushes the pattern. Used together with @link
     *        PigeonholeFinder#windowFindBegin @endlink and @link
     *        PigeonholeFinder#windowFindNext @endlink.
     *
     * @signature void windowFindEnd(finder, pattern);
     *
     * @param[in,out] pattern A pattern with window interface.
     * @param[in,out] finder A finder with window interface. Types: @link
     *                       PigeonholeFinder @endlink
     *
     * @see PigeonholeFinder#windowFindBegin
     * @see PigeonholeFinder#windowFindNext
     *
     * @fn PigeonholeFinder#getWindowFindHits
     *
     * @headerfile <seqan/index/find_pigeonhole.h>
     *
     * @brief Returns the string of hits from the finder.
     *
     * @signature THitString getWindowFindHits(finder);
     *
     * @param[in] finder A PigeonFinder.
     *
     * @return THitString @link String @endlink of Hits, see @link
     *                    PigeonholeFinder::THitString @endlink.
     *
     * @see PigeonholeFinder#windowFindNext
     */