Seed - SeqAn API Documentation

# Class Seed
Stores the start and end positions in the horizonal and vertical dimension.

All Subcl's | ChainedSeed, SimpleSeed
Defined in | <seqan/seeds.h>
Signature | `template <typename TSpec[, typename TConfig]> class Seed;`

## Template Parameters

`TSpec` | The seed specialization type.
`TConfig` | The configuration object to use for this seed, defaults to DefaultSeedConfig.

## Interface Function Overview

- `TDiagonal beginDiagonal(seed);`
  Returns the begin diagonal of a Seed.
- `TPosition beginPositionH(seed);`
  Returns the begin position of the seed in the database (horizontal direction).
- `TPosition beginPositionV(seed);`
  Returns the begin position of the seed in the query (vertical direction).
- `TDiagonal endDiagonal(seed);`
  Returns the end diagonal of a Seed.
- `TPosition endPositionH(seed);`
  Returns the end position of the seed in the database (horizontal direction).
- `TPosition endPositionV(seed);`
  Returns the end position of the seed in the query (vertical direction).
- `void extendSeed(seed, database, query, direction, MatchExtend);, void extendSeed(seed, database, query, direction, scoringScheme, scoreDropOff, xDropTag);`
  Extends a seed.
- `TDiagonal lowerDiagonal(seed);`
  Returns the leftmost diagonal of the seed (minimum diagonal value).
- `TSeedScore score(seed);`
  Returns the score of a Seed.
- `TSize seedSize(seed);`
  Returns the number of matches and mismatches of the seed. This is the longest true diagonal fitting into its dimensions.
- `void setBeginPositionH(seed, pos);`
  Sets the begin position of the seed in the database (horizontal direction).
- `void setBeginPositionV(seed, pos);`
  Sets the begin position of the seed in the query (vertical direction).
- `void setEndPositionH(seed, pos);`
  Sets the end position of the seed in the database (horizontal direction).
- `void setEndPositionV(seed, pos);`
  Sets the end position of the seed in the query (vertical direction).
- `void setLowerDigonal(seed, diag);`
  Sets a new value for the leftmost diagonal of a seed.
- `void setScore(seed, scoreVal);`
  Sets the Seed score value.
- `void setUpperDigonal(seed, diag);`
  Sets a new value for the rightmost diagonal of a seed.
- `TDiagonal upperDiagonal(seed);`
  Returns the rightmost diagonal of the seed (maximum diagonal value).

## Interface Metafunction Overview

- `Diagonal<TSeed>::Type;`
  The diagonal type of a Seed.
- `Position<TSeed>::Type;`
  The position type of a Seed.
- `SeedScore<TSeed>::Type;`
  The seed score type of a Seed.
- `Size<TSeed>::Type;`
  The size type of a Seed.

## Detailed Description

### Examples

The following example shows the usage of three seed extension algorithms using the tags `MaxExtend`, `UnGappedXDrop`, and `GappedXDrop`.

    //Examples for three seed extension algorithms.
    #include <iostream>
    #include <seqan/seeds.h>

    using namespace seqan2;

    int main()
    {
        String<char> a = "SEEDabXcdXefXXX";
        String<char> b = "SEEDabYcdefYYYY";

        Seed<Simple> seed1(0, 0, 4);          //left=0; length=4
        extendSeed(seed1, a, b, EXTEND_BOTH, MatchExtend());
        std::cout << "endPositionH(seed1) = " << endPositionH(seed1) << std::endl;
        std::cout << "endPositionV(seed1) = " << endPositionV(seed1) << std::endl;

        Seed<Simple> seed2(0, 0, 4);          //left=0; length=4
        Score<> scoring(1, -1, -1);
        extendSeed(seed2, a, b, EXTEND_BOTH, scoring, 2, UnGappedXDrop());
        std::cout << "endPositionH(seed2) = " << endPositionH(seed2) << std::endl;
        std::cout << "endPositionV(seed2) = " << endPositionV(seed2) << std::endl;

        Seed<Simple> seed3(0, 0, 4);          //left=0; length=4
        extendSeed(seed3, a, b, EXTEND_BOTH, scoring, 2, GappedXDrop());
        std::cout << "endPositionH(seed3) = " << endPositionH(seed3) << std::endl;
        std::cout << "endPositionV(seed3) = " << endPositionV(seed3) << std::endl;

        return 0;
    }

Demo: demos/dox/seeds/seeds_extension.cpp

The output is as follows:

    endPositionH(seed1) = 6
    endPositionV(seed1) = 6
    endPositionH(seed2) = 9
    endPositionV(seed2) = 9
    endPositionH(seed3) = 14
    endPositionV(seed3) = 13

Here is an example for global seed chaining:

    #include <iostream>
    #include <seqan/seeds.h>

    using namespace seqan2;

    int main()
    {
        // Build SeedSet.
        SeedSet<Seed<Simple>, Unordered> seedSet;
        addSeed(seedSet, Seed<Simple>(0, 93, 281, 342), Single());
        addSeed(seedSet, Seed<Simple>(3, 237, 127, 364), Single());
        addSeed(seedSet, Seed<Simple>(3, 284, 86, 368), Single());
        addSeed(seedSet, Seed<Simple>(5, 146, 239, 374), Single());
        addSeed(seedSet, Seed<Simple>(299, 352, 405, 460), Single());

        // Perform sparse chaining, uses time O(n log n).
        String<Seed<Simple> > chain;
        chainSeedsGlobally(chain, seedSet, SparseChaining());

        // Print results to stdout.
        for (unsigned i = 0; i < length(chain); ++i)
            std::cout << "Seed(" << beginPositionH(chain[i]) << ", "
                      << beginPositionV(chain[i]) << ", " << endPositionH(chain[i])
                      << ", " << endPositionV(chain[i]) << ")\n";

        return 0;
    }

Demo: demos/dox/seeds/seeds_chaining.cpp

## Interface Functions Detail

### `TDiagonal beginDiagonal(seed);`

Returns the begin diagonal of a Seed.

#### Parameters

`seed` | The Seed to query for its begin diagonal.

#### Returns

`TDiagonal` | The diagonal of the Seed's begin position of type Diagonal.

#### Data Races

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

### `TPosition beginPositionH(seed);`

Returns the begin position of the seed in the database (horizontal direction).

#### Parameters

`seed` | The seed to query.

#### Returns

`TPosition` | The horizontal begin position of type Position.

#### Data Races

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

### `TPosition beginPositionV(seed);`

Returns the begin position of the seed in the query (vertical direction).

#### Parameters

`seed` | The seed to query.

#### Returns

`TPosition` | The vertical begin position of type Position.

#### Data Races

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

### `TDiagonal endDiagonal(seed);`

Returns the end diagonal of a Seed.

#### Parameters

`seed` | The Seed to query for its end diagonal.

#### Returns

`TDiagonal` | The diagonal of the Seed's end position of type Diagonal.

#### Data Races

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

### `TPosition endPositionH(seed);`

Returns the end position of the seed in the database (horizontal direction).

#### Parameters

`seed` | The seed to query.

#### Returns

`TPosition` | The horizontal end position of type Position.

#### Data Races

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

### `TPosition endPositionV(seed);`

Returns the end position of the seed in the query (vertical direction).

#### Parameters

`seed` | The seed to query.

#### Returns

`TPosition` | The vertical end position of type Position.

#### Data Races

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

### `void extendSeed(seed, database, query, direction, MatchExtend); void extendSeed(seed, database, query, direction, scoringScheme, scoreDropOff, xDropTag);`

Extends a seed.

#### Parameters

`seed` | The Seed to extend.
`database` | The database (horizontal) sequence.
`query` | The query (vertical) sequence.
`direction` | The extension direction. Type: ExtensionDirection.
`scoringScheme` | The Score object to use for scoring alignments and gaps.
`scoreDropOff` | The score drop after which the extension should stop. The extension stops if this value is exceeded. Only given for when using an x-drop algorithm.
`xDropTag` | Tag for selecting x-drop method, one of `UnGappedXDrop` and `GappedXDrop`.

You can use the tags, `MatchExtend`, `UnGappedXDrop`, and `GappedXDrop`.

Note that the diagonals updated in `seed` do not necessarily reflect the diagonals for the optimal extension but the diagonals used in all traces of the extension. However, they are guaranteed to include the optimal extension's trace.

#### Examples

The documentation of the class Seed contains an example for seed extension.

#### Data Races

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

#### See Also

- ExtensionDirection
- SeedExtensionTags

### `TDiagonal lowerDiagonal(seed);`

Returns the leftmost diagonal of the seed (minimum diagonal value).

#### Parameters

`seed` | The seed to query for its lower diagonal.

#### Returns

`TDiagonal` | The lower diagonal value of type Diagonal.

#### Data Races

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

### `TSeedScore score(seed);`

Returns the score of a Seed.

#### Parameters

`seed` | The Seed to query for its score.

#### Returns

`TSeedScore` | The score value of the seed of type SeedScore.

#### Data Races

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

### `TSize seedSize(seed);`

Returns the number of matches and mismatches of the seed. This is the longest true diagonal fitting into its dimensions.

#### Parameters

`seed` | The Seed to query for its size.

#### Returns

`TSize` | The size of the type Size.

#### Data Races

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

### `void setBeginPositionH(seed, pos);`

Sets the begin position of the seed in the database (horizontal direction).

#### Parameters

`seed` | The Seed to set the horizontal begin position for.
`pos` | The value to set for the horizontal begin position.

#### Data Races

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

### `void setBeginPositionV(seed, pos);`

Sets the begin position of the seed in the query (vertical direction).

#### Parameters

`seed` | The Seed to set the vertical begin position for.
`pos` | The value to set for the vertical begin position.

#### Data Races

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

### `void setEndPositionH(seed, pos);`

Sets the end position of the seed in the database (horizontal direction).

#### Parameters

`seed` | The Seed to set the horizontal end position for.
`pos` | The value to set for the horizontal end position.

#### Data Races

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

### `void setEndPositionV(seed, pos);`

Sets the end position of the seed in the query (vertical direction).

#### Parameters

`seed` | The Seed to set the vertical end position for.
`pos` | The value to set for the vertical end position.

#### Data Races

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

### `void setLowerDigonal(seed, diag);`

Sets a new value for the leftmost diagonal of a seed.

#### Parameters

`seed` | The Seed to set the diagonal value for.
`diag` | The value to set for the diagonal.

#### Data Races

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

### `void setScore(seed, scoreVal);`

Sets the Seed score value.

#### Parameters

`seed` | The Seed to set the score value of.
`scoreVal` | The score value to set. The type can queried from the type of `seed` using SeedScore.

#### Data Races

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

### `void setUpperDigonal(seed, diag);`

Sets a new value for the rightmost diagonal of a seed.

#### Parameters

`seed` | The Seed to set the diagonal value for.
`diag` | The value to set for the diagonal.

#### Data Races

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

### `TDiagonal upperDiagonal(seed);`

Returns the rightmost diagonal of the seed (maximum diagonal value).

#### Parameters

`seed` | The seed to query for its upper diagonal.

#### Returns

`TDiagonal` | The upper diagonal value of type Diagonal.

#### Data Races

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

## Interface Metafunctions Detail

### `Diagonal<TSeed>::Type;`

The diagonal type of a Seed.

#### Template Parameters

`TSeed` | The Seed to query for its diagonal type.

#### Returns

`Type` | The diagonal type of `TSeed`.

### `Position<TSeed>::Type;`

The position type of a Seed.

#### Template Parameters

`TSeed` | The Seed type to query.

#### Returns

`Type` | The position type of `TSeed`.

### `SeedScore<TSeed>::Type;`

The seed score type of a Seed.

#### Template Parameters

`TSeed` | The Seed to query for its seed score type.

#### Returns

`Type` | The score type of `TSeed`.

### `Size<TSeed>::Type;`

The size type of a Seed.

#### Template Parameters

`TSeed` | The Seed to query for its size type.

#### Returns

`Type` | The size type of `TSeed`.

#### Dox Sources

    /*!
     * @class Seed
     *
     * @headerfile <seqan/seeds.h>
     *
     * @brief Stores the start and end positions in the horizonal and vertical
     *        dimension.
     *
     * @signature template <typename TSpec[, typename TConfig]> class Seed;
     *
     * @tparam TSpec The seed specialization type.
     * @tparam TConfig The configuration object to use for this seed, defaults to
     *                 @link DefaultSeedConfig @endlink.
     *
     * @section Examples
     *
     * The following example shows the usage of three seed extension algorithms
     * using the tags <tt>MaxExtend</tt>, <tt>UnGappedXDrop</tt>, and
     * <tt>GappedXDrop</tt>.
     *
     * @include demos/dox/seeds/seeds_extension.cpp
     *
     * The output is as follows:
     *
     * @include demos/dox/seeds/seeds_extension.cpp.stdout
     *
     * Here is an example for global seed chaining:
     *
     * @include demos/dox/seeds/seeds_chaining.cpp
     *
     *
     *
     * @fn Seed#extendSeed
     *
     * @headerfile <seqan/seeds.h>
     *
     * @brief Extends a seed.
     *
     * @signature void extendSeed(seed, database, query, direction, MatchExtend);
     * @signature void extendSeed(seed, database, query, direction, scoringScheme,
     *            scoreDropOff, xDropTag);
     *
     * @param[in,out] seed The Seed to extend.
     * @param[in] database The database (horizontal) @link ContainerConcept sequence
     *                     @endlink.
     * @param[in] query The query (vertical) @link ContainerConcept sequence
     *                  @endlink.
     * @param[in] direction The extension direction. Type: @link ExtensionDirection
     *                      @endlink.
     * @param[in] scoringScheme The @link Score @endlink object to use for scoring
     *                          alignments and gaps.
     * @param[in] scoreDropOff The score drop after which the extension should stop.
     *                         The extension stops if this value is exceeded. Only
     *                         given for when using an x-drop algorithm.
     * @param[in] xDropTag Tag for selecting x-drop method, one of
     *                     <tt>UnGappedXDrop</tt> and <tt>GappedXDrop</tt>.
     *
     * You can use the tags, <tt>MatchExtend</tt>, <tt>UnGappedXDrop</tt>, and
     * <tt>GappedXDrop</tt>.
     *
     * Note that the diagonals updated in <tt>seed</tt> do not necessarily reflect
     * the diagonals for the optimal extension but the diagonals used in all traces
     * of the extension. However, they are guaranteed to include the optimal
     * extension's trace.
     *
     * @section Examples
     *
     * The documentation of the class @link Seed @endlink contains an example for
     * seed extension.
     *
     * @see ExtensionDirection
     * @see SeedExtensionTags
     *
     * @fn Seed#beginPositionH
     *
     * @brief Returns the begin position of the seed in the database (horizontal
     *        direction).
     *
     * @signature TPosition beginPositionH(seed);
     *
     * @param[in] seed The seed to query.
     *
     * @return TPosition The horizontal begin position of type @link Seed#Position
     *                   @endlink.
     *
     * @fn Seed#endPositionH
     *
     * @brief Returns the end position of the seed in the database (horizontal
     *        direction).
     *
     * @signature TPosition endPositionH(seed);
     *
     * @param[in] seed The seed to query.
     *
     * @return TPosition The horizontal end position of type @link Seed#Position
     *                   @endlink.
     *
     * @fn Seed#setBeginPositionH
     *
     * @brief Sets the begin position of the seed in the database (horizontal
     *        direction).
     *
     * @signature void setBeginPositionH(seed, pos);
     *
     * @param[in,out] seed The Seed to set the horizontal begin position for.
     * @param[in] pos The value to set for the horizontal begin position.
     *
     * @fn Seed#setEndPositionH
     *
     * @brief Sets the end position of the seed in the database (horizontal
     *        direction).
     *
     * @signature void setEndPositionH(seed, pos);
     *
     * @param[in,out] seed The Seed to set the horizontal end position for.
     * @param[in] pos The value to set for the horizontal end position.
     *
     * @fn Seed#beginPositionV
     *
     * @brief Returns the begin position of the seed in the query (vertical
     *        direction).
     *
     * @signature TPosition beginPositionV(seed);
     *
     * @param[in] seed The seed to query.
     *
     * @return TPosition The vertical begin position of type @link Seed#Position
     *                   @endlink.
     *
     * @fn Seed#endPositionV
     *
     * @brief Returns the end position of the seed in the query (vertical
     *        direction).
     *
     * @signature TPosition endPositionV(seed);
     *
     * @param[in] seed The seed to query.
     *
     * @return TPosition The vertical end position of type @link Seed#Position
     *                   @endlink.
     *
     * @fn Seed#setBeginPositionV
     *
     * @brief Sets the begin position of the seed in the query (vertical direction).
     *
     * @signature void setBeginPositionV(seed, pos);
     *
     * @param[in,out] seed The Seed to set the vertical begin position for.
     * @param[in] pos The value to set for the vertical begin position.
     *
     * @fn Seed#setEndPositionV
     *
     * @brief Sets the end position of the seed in the query (vertical direction).
     *
     * @signature void setEndPositionV(seed, pos);
     *
     * @param[in,out] seed The Seed to set the vertical end position for.
     * @param[in] pos The value to set for the vertical end position.
     *
     * @fn Seed#lowerDiagonal
     *
     * @brief Returns the leftmost diagonal of the seed (minimum diagonal value).
     *
     * @signature TDiagonal lowerDiagonal(seed);
     *
     * @param[in] seed The seed to query for its lower diagonal.
     *
     * @return TDiagonal The lower diagonal value of type @link Seed#Diagonal
     *                   @endlink.
     *
     * @fn Seed#setLowerDiagonal
     *
     * @brief Sets a new value for the leftmost diagonal of a seed.
     *
     * @signature void setLowerDigonal(seed, diag);
     *
     * @param[in,out] seed The Seed to set the diagonal value for.
     * @param[in] diag The value to set for the diagonal.
     *
     * @fn Seed#upperDiagonal
     *
     * @brief Returns the rightmost diagonal of the seed (maximum diagonal value).
     *
     * @signature TDiagonal upperDiagonal(seed);
     *
     * @param[in] seed The seed to query for its upper diagonal.
     *
     * @return TDiagonal The upper diagonal value of type @link Seed#Diagonal
     *                   @endlink.
     *
     * @fn Seed#setUpperDiagonal
     *
     * @brief Sets a new value for the rightmost diagonal of a seed.
     *
     * @signature void setUpperDigonal(seed, diag);
     *
     * @param[in,out] seed The Seed to set the diagonal value for.
     * @param[in] diag The value to set for the diagonal.
     *
     * @fn Seed#seedSize
     *
     * @brief Returns the number of matches and mismatches of the seed. This is the
     *        longest true diagonal fitting into its dimensions.
     *
     * @signature TSize seedSize(seed);
     *
     * @param[in] seed The Seed to query for its size.
     *
     * @return TSize The size of the type @link Seed#Size @endlink.
     *
     * @fn Seed#beginDiagonal
     *
     * @brief Returns the begin diagonal of a Seed.
     *
     * @signature TDiagonal beginDiagonal(seed);
     *
     * @param[in] seed The Seed to query for its begin diagonal.
     *
     * @return TDiagonal The diagonal of the Seed's begin position of type @link
     *                   Seed#Diagonal @endlink.
     *
     * @fn Seed#endDiagonal
     *
     * @brief Returns the end diagonal of a Seed.
     *
     * @signature TDiagonal endDiagonal(seed);
     *
     * @param[in] seed The Seed to query for its end diagonal.
     *
     * @return TDiagonal The diagonal of the Seed's end position of type @link
     *                   Seed#Diagonal @endlink.
     *
     * @fn Seed#score
     *
     * @brief Returns the score of a Seed.
     *
     * @signature TSeedScore score(seed);
     *
     * @param[in] seed The Seed to query for its score.
     *
     * @return TSeedScore The score value of the seed of type @link Seed#SeedScore
     *                    @endlink.
     *
     * @fn Seed#setScore
     *
     * @brief Sets the Seed score value.
     *
     * @signature void setScore(seed, scoreVal);
     *
     * @param[in,out] seed The Seed to set the score value of.
     * @param[in] scoreVal The score value to set. The type can queried from the
     *                     type of <tt>seed</tt> using @link Seed#SeedScore
     *                     @endlink.
     *
     * @mfn Seed#Position
     *
     * @brief The position type of a Seed.
     *
     * @signature Position<TSeed>::Type;
     *
     * @tparam TSeed The Seed type to query.
     *
     * @return Type The position type of <tt>TSeed</tt>.
     *
     * @mfn Seed#Size
     *
     * @brief The size type of a Seed.
     *
     * @signature Size<TSeed>::Type;
     *
     * @tparam TSeed The Seed to query for its size type.
     *
     * @return Type The size type of <tt>TSeed</tt>.
     *
     * @mfn Seed#Diagonal
     *
     * @brief The diagonal type of a Seed.
     *
     * @signature Diagonal<TSeed>::Type;
     *
     * @tparam TSeed The Seed to query for its diagonal type.
     *
     * @return Type The diagonal type of <tt>TSeed</tt>.
     *
     * @mfn Seed#SeedScore
     *
     * @brief The seed score type of a Seed.
     *
     * @signature SeedScore<TSeed>::Type;
     *
     * @tparam TSeed The Seed to query for its seed score type.
     *
     * @return Type The score type of <tt>TSeed</tt>.
     */