Shape - SeqAn API Documentation

# Class Shape
Stores hash value and shape for an ungapped or gapped q-gram.

All Subcl's | GappedShape, GenericShape, HardwiredShape, OneGappedShape, SimpleShape, UngappedShape
Defined in | <seqan/index.h>
Signature | `template <typename TValue, typename TSpec> class Shape;`

## Template Parameters

`TSpec` | The specializing type. Default: SimpleShape, for ungapped q-grams.
`TValue` | The Value type of the string the shape is applied to (e.g. `Dna`).

## Interface Function Overview

- `TValue hash(shape, it[, charsLeft]);`
  Computes a (lower) hash value for a shape applied to a sequence.
- `TValue hash2(shape, it, charsLeft);`
  Computes an unique hash value of a shape applied to a sequence, even if the sequence is shorter than the shape span.
- `TValue hash2Next(shape, it);`
  Computes a unique hash value for the adjacent shape, even if it is shorter than q.
- `TValue hash2Upper(shape, it, charsLeft);`
  Computes an upper unique hash value of a shape applied to a sequence, even if the sequence is shorter than the shape span.
- `void hashInit(shape, it);`
  Preprocessing step of a pure hashNext loop.
- `TValue hashNext(shape, it);`
  Computes the hash value for the adjacent shape.
- `TValue hashUpper(shape, it, charsLeft);`
  Computes an upper hash value for a shape applied to a sequence.
- `TSize length(shape);`
  Returns the number of elements of the shape (span).
- `TSize resize(shape, length)`
  Resize a shape to a specified span.
- `void shapeToString(bitmap, shape);`
  Converts a given shape into a sequence of '1' (relevant position) and '0' (irrelevant position).
- `bool stringToShape(shape, bitmap);`
  Takes a shape given as a string of '1' (relevant position) and '0' (irrelevant position) and converts it into a Shape object.
- `void unhash(result, hash, q);`
  Inverse of the hash function; for ungapped shapes.
- `TValue value(shape);`
  Returns the current hash value of the Shape.
- `TSize weight(shape);`
  Number of relevant positions in a shape.

## Interface Metafunction Overview

- `Host<TShape>::Type;`
  Returns the host (= value) type to use.
- `LENGTH<TShape>::VALUE;`
  Returns the length (span) of a shape.
- `Size<TShape>::Type;`
  Returns the size type for a shape.
- `Value<TShape>::Type;`
  Returns the value type for a shape.
- `ValueSize<TShape>::Type;`
  Returns the type to use for the value size.
- `WEIGHT<TShape>::VALUE;`
  Returns the weight (number of 1's) of a shape.

## Detailed Description

The ValueSize of Shape is the ValueSize of TValue which is the alphabet size.

To get the span or the weight of a shape call length or weight.

## Interface Functions Detail

### `TValue hash(shape, it[, charsLeft]);`

Computes a (lower) hash value for a shape applied to a sequence.

#### Parameters

`shape` | Shape to be used for hashing. Types: Shape
`it` | Sequence iterator pointing to the first character of the shape.
`charsLeft` | The distance of `it` to the string end. If `charsLeft` is smaller than the shape's span, the hash value corresponds to the smallest shape beginning with `charsLeft` characters.

#### Returns

`TValue` | Hash value of the shape (Metafunction: Value).

#### Data Races

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

#### See Also

- hash2
- hashNext
- hashUpper
- unhash

### `TValue hash2(shape, it, charsLeft);`

Computes an unique hash value of a shape applied to a sequence, even if the sequence is shorter than the shape span.

#### Parameters

`shape` | Shape to be used for hashing. Types: Shape
`it` | Sequence iterator pointing to the first character of the shape.
`charsLeft` | The distance of `it` to the string end.

#### Returns

`TValue` | Hash value of the shape (Metafunction: Value).

#### Data Races

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

#### See Also

- hash
- hash2Next
- hash2Upper
- unhash

### `TValue hash2Next(shape, it);`

Computes a unique hash value for the adjacent shape, even if it is shorter than q.

#### Parameters

`shape` | Shape to be used for hashing the q-gram. Types: Shape
`it` | Sequence iterator pointing to the first character of the adjacent shape.

#### Returns

`TValue` | Hash value of the shape (Metafunction: Value).

hash has to be called before with `shape` on the left adjacent q-gram.

#### Data Races

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

#### See Also

- hash2

### `TValue hash2Upper(shape, it, charsLeft);`

Computes an upper unique hash value of a shape applied to a sequence, even if the sequence is shorter than the shape span.

#### Parameters

`shape` | Shape to be used for hashing. Types: Shape
`it` | Sequence iterator pointing to the first character of the shape.
`charsLeft` | The distance of `it` to the string end.

#### Returns

`TValue` | Upper hash value of the shape. The hash value corresponds to the maximal hash2 value of a shape beginning with the `min(charsLeft,length(shape))` characters + 1 (Metafunction: Value).

This function in conjunction with hash2 is useful to search a q-gram index for p-grams with p < q.

#### Data Races

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

#### See Also

- hash2

### `void hashInit(shape, it);`

Preprocessing step of a pure hashNext loop.

#### Parameters

`shape` | Shape to be used for hasing.
`it` | The iterator to use for initializing the shape.

Overlapping q-grams can efficiently be hashed by calling hash on the first text position and hashNext on succeeding, adjacent positions. One drawback of this scenario is that for-loops cannot start with the first position directly and become more complicated. As a remedy, hashInit was introduced which initializes the Shape to be used with hashNext on the first position directly.

#### Example

Two hash loop examples. The first loop uses hash/hashNext while the second use hashInit/hashNext and can process all hashes within the loop.

    #include <seqan/sequence.h>
    #include <seqan/index.h>

    using namespace seqan;

    int main()
    {
        DnaString text = "AAAACACAGTTTGA";
        Shape<Dna, UngappedShape<3> > myShape;

        // loop using hash() and hashNext() starts at position 1
        std::cout << hash(myShape, begin(text)) << '\t';
        for (unsigned i = 1; i < length(text) - length(myShape) + 1; ++i)
            std::cout << hashNext(myShape, begin(text) + i) << '\t';
        std::cout << std::endl;

        // loop using hashInit() and hashNext() starts at position 0
        hashInit(myShape, begin(text));
        for (unsigned i = 0; i < length(text) - length(myShape) + 1; ++i)
            std::cout << hashNext(myShape, begin(text) + i) << '\t';
        std::cout << std::endl;

        return 0;
    }

Demo: demos/dox/index/shape_hash_init.cpp

    0    0    1    4    17    4    18    11    47    63    62    56
    0    0    1    4    17    4    18    11    47    63    62    56

#### Data Races

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

### `TValue hashNext(shape, it);`

Computes the hash value for the adjacent shape.

#### Parameters

`shape` | Shape to be used for hashing. Types: Shape
`it` | Sequence iterator pointing to the first character of the adjacent shape.

#### Returns

`TValue` | Hash value of the q-gram (Metafunction: Value).

hash has to be called before.

#### Data Races

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

#### See Also

- hash

### `TValue hashUpper(shape, it, charsLeft);`

Computes an upper hash value for a shape applied to a sequence.

#### Parameters

`shape` | Shape to be used for hashing. Types: Shape
`it` | Sequence iterator pointing to the first character of the shape.
`charsLeft` | The distance of `it` to the string end.

#### Returns

`TValue` | Upper hash value of the shape. The hash value corresponds to the maximal hash value of a shape beginning with `min(charsLeft,length(shape))` characters + 1 (Metafunction: Value).

This function in conjunction with hash is useful to search a q-gram index for p-grams with p < q.

#### Data Races

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

#### See Also

- hash

### `TSize length(shape);`

Returns the number of elements of the shape (span).

#### Parameters

`shape` | Shape object for which the number of relevant positions is determined.

#### Returns

`TSize` | The number of elements of the shape (span) (Metafunction: Size).

#### Data Races

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

### `TSize resize(shape, length)`

Resize a shape to a specified span.

#### Parameters

`shape` | Shape object for which the number of relevant positions is determined
`length` | The new length (span) of the shape.

#### Returns

`TSize` | The new span of type (Metafunction: Size).

#### Data Races

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

### `void shapeToString(bitmap, shape);`

Converts a given shape into a sequence of '1' (relevant position) and '0' (irrelevant position).

#### Parameters

`bitmap` | The resulting sequence object. Types: String
`shape` | Shape object. Types: Shape

#### Data Races

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

#### See Also

- stringToShape

### `bool stringToShape(shape, bitmap);`

Takes a shape given as a string of '1' (relevant position) and '0' (irrelevant position) and converts it into a Shape object.

#### Parameters

`shape` | Shape object that is manipulated.
`bitmap` | A character string of '1' and '0' representing relevant and irrelevant positions (blanks) respectively. This string must begin with a '1'. Trailing '0's are ignored. If `shape` is a SimpleShape at most one contiguous sequences of `1`s is allowed. If `shape` is a OneGappedShape at most two contiguous sequences of '1's are allowed (String of `char`).

#### Returns

`bool` | `true` if the conversion was successful.

#### Data Races

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

#### See Also

- reverse
- shapeToString

### `void unhash(result, hash, q);`

Inverse of the hash function; for ungapped shapes.

#### Parameters

`result` | String to write the result to. Types: String.
`hash` | The hash value previously computed with hash.
`q` | The `q`-gram length. Types: `unsigned`

#### Data Races

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

#### See Also

- hash
- hash2

### `TValue value(shape);`

Returns the current hash value of the Shape.

#### Parameters

`shape` | The Shape to query for its value.

#### Returns

`TValue` | The hash value of the shape.

#### Data Races

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

### `TSize weight(shape);`

Number of relevant positions in a shape.

#### Parameters

`shape` | Shape object for which the number of relevant positions is determined.

#### Returns

`TSize` | Number of relevant positions (Metafunction: Size).

For ungapped shapes the return value is the result of the length function. For gapped shapes this is the number of '1's.

#### Data Races

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

## Interface Metafunctions Detail

### `Host<TShape>::Type;`

Returns the host (= value) type to use.

#### Template Parameters

`TShape` | The Shape to query for host (= value) type.

#### Returns

`Type` | Type to use for the host (= value) size.

### `LENGTH<TShape>::VALUE;`

Returns the length (span) of a shape.

#### Template Parameters

`TShape` | The Shape to query for its length (span).

#### Returns

`VALUE` | The length (span) of the shape.

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

Returns the size type for a shape.

#### Template Parameters

`TShape` | The Shape to query for its size type.

#### Returns

`Type` | The size type of the shape.

### `Value<TShape>::Type;`

Returns the value type for a shape.

#### Template Parameters

`TShape` | The Shape to query for its value type.

#### Returns

`Type` | The value type of the shape.

### `ValueSize<TShape>::Type;`

Returns the type to use for the value size.

#### Template Parameters

`TShape` | The Shape to query for value size type.

#### Returns

`Type` | Type to use for the value size.

### `WEIGHT<TShape>::VALUE;`

Returns the weight (number of 1's) of a shape.

#### Template Parameters

`TShape` | The Shape to query for its weight (number of 1's).

#### Returns

`VALUE` | The weight (number of 1's) of the shape.

#### Dox Sources

    /*!
     * @class Shape
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Stores hash value and shape for an ungapped or gapped q-gram.
     *
     * @signature template <typename TValue, typename TSpec> class Shape;
     *
     * @tparam TSpec The specializing type. Default: @link SimpleShape @endlink, for
     *               ungapped q-grams.
     * @tparam TValue The @link Value @endlink type of the string the shape is
     *                applied to (e.g. <tt>Dna</tt>).
     *
     * The @link FiniteOrderedAlphabetConcept#ValueSize @endlink of Shape is the
     * ValueSize of TValue which is the alphabet size.
     *
     * To get the span or the weight of a shape call @link Shape#length @endlink or
     * @link Shape#weight @endlink.
     *
     * @mfn Shape#Value
     *
     * @brief Returns the value type for a shape.
     *
     * @signature Value<TShape>::Type;
     *
     * @tparam TShape The Shape to query for its value type.
     *
     * @return Type The value type of the shape.
     *
     * @mfn Shape#Size
     *
     * @brief Returns the size type for a shape.
     *
     * @signature Size<TShape>::Type;
     *
     * @tparam TShape The Shape to query for its size type.
     *
     * @return Type The size type of the shape.
     *
     * @mfn Shape#LENGTH
     *
     * @brief Returns the length (span) of a shape.
     *
     * @signature LENGTH<TShape>::VALUE;
     *
     * @tparam TShape The Shape to query for its length (span).
     *
     * @return VALUE The length (span) of the shape.
     *
     * @mfn Shape#WEIGHT
     *
     * @brief Returns the weight (number of 1's) of a shape.
     *
     * @signature WEIGHT<TShape>::VALUE;
     *
     * @tparam TShape The Shape to query for its weight (number of 1's).
     *
     * @return VALUE The weight (number of 1's) of the shape.
     *
     * @mfn Shape#ValueSize
     *
     * @brief Returns the type to use for the value size.
     *
     * @signature ValueSize<TShape>::Type;
     *
     * @tparam TShape The Shape to query for value size type.
     *
     * @return Type Type to use for the value size.
     *
     * @mfn Shape#Host
     *
     * @brief Returns the host (= value) type to use.
     *
     * @signature Host<TShape>::Type;
     *
     * @tparam TShape The Shape to query for host (= value) type.
     *
     * @return Type Type to use for the host (= value) size.
     *
     * @fn Shape#value
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the current hash value of the Shape.
     *
     * @signature TValue value(shape);
     *
     * @param[in] shape The Shape to query for its value.
     *
     * @return TValue The hash value of the shape.
     *
     * @fn Shape#length
     *
     * @brief Returns the number of elements of the shape (span).
     *
     * @signature TSize length(shape);
     *
     * @param[in] shape Shape object for which the number of relevant positions is
     *                  determined.
     *
     * @return TSize The number of elements of the shape (span) (Metafunction: @link
     *               Shape#Size @endlink).
     *
     * @fn Shape#weight
     *
     * @brief Number of relevant positions in a shape.
     *
     * @signature TSize weight(shape);
     *
     * @param[in] shape Shape object for which the number of relevant positions is
     *                  determined.
     *
     * @return TSize Number of relevant positions (Metafunction: @link Shape#Size
     *               @endlink).
     *
     * For ungapped shapes the return value is the result of the @link Shape#length
     * @endlink function. For gapped shapes this is the number of '1's.
     *
     * @fn Shape#resize
     *
     * @brief Resize a shape to a specified span.
     *
     * @signature TSize resize(shape, length)
     *
     * @param[in,out] shape Shape object for which the number of relevant positions
     *                      is determined
     * @param[in] length The new length (span) of the shape.
     *
     * @return TSize The new span of type (Metafunction: @link Shape#Size @endlink).
     *
     * @fn Shape#hash
     *
     * @brief Computes a (lower) hash value for a shape applied to a sequence.
     *
     * @signature TValue hash(shape, it[, charsLeft]);
     *
     * @param[in,out] shape Shape to be used for hashing. Types: @link Shape
     *                      @endlink
     * @param[in] it Sequence iterator pointing to the first character of the shape.
     * @param[in] charsLeft The distance of <tt>it</tt> to the string end. If
     *                      <tt>charsLeft</tt> is smaller than the shape's span, the
     *                      hash value corresponds to the smallest shape beginning
     *                      with <tt>charsLeft</tt> characters.
     *
     * @return TValue Hash value of the shape (Metafunction: @link Shape#Value
     *                @endlink).
     *
     * @see Shape#hashNext
     * @see Shape#hashUpper
     * @see Shape#hash2
     * @see Shape#unhash
     *
     * @fn Shape#hashInit
     *
     * @brief Preprocessing step of a pure @link Shape#hashNext @endlink loop.
     *
     * @signature void hashInit(shape, it);
     *
     * @param[in,out] shape Shape to be used for hasing.
     * @param[in] it The @link IteratorAssociatedTypesConcept iterator @endlink to
     *               use for initializing the shape.
     *
     * Overlapping q-grams can efficiently be hashed by calling @link Shape#hash
     * @endlink on the first text position and @link Shape#hashNext @endlink on
     * succeeding, adjacent positions. One drawback of this scenario is that for-
     * loops cannot start with the first position directly and become more
     * complicated. As a remedy, @link Shape#hashInit @endlink was introduced which
     * initializes the Shape to be used with @link Shape#hashNext @endlink on the
     * first position directly.
     *
     * @section Example
     *
     * Two hash loop examples. The first loop uses @link Shape#hash @endlink/@link
     * Shape#hashNext @endlink while the second use @link Shape#hashInit
     * @endlink/@link Shape#hashNext @endlink and can process all hashes within the
     * loop.
     *
     * @include demos/dox/index/shape_hash_init.cpp
     *
     * @code{.stdout}
     * 0    0    1    4    17    4    18    11    47    63    62    56
     * 0    0    1    4    17    4    18    11    47    63    62    56
     * @endcode
     *
     *
     * @fn Shape#hashUpper
     *
     * @brief Computes an upper hash value for a shape applied to a sequence.
     *
     * @signature TValue hashUpper(shape, it, charsLeft);
     *
     * @param[in,out] shape Shape to be used for hashing. Types: @link Shape
     *                      @endlink
     * @param[in] it Sequence iterator pointing to the first character of the shape.
     * @param[in] charsLeft The distance of <tt>it</tt> to the string end.
     *
     * @return TValue Upper hash value of the shape. The hash value corresponds to
     *                the maximal @link Shape#hash @endlink value of a shape
     *                beginning with <tt>min(charsLeft,length(shape))</tt>
     *                characters + 1 (Metafunction: @link Shape#Value @endlink).
     *
     * This function in conjunction with @link Shape#hash @endlink is useful to
     * search a q-gram index for p-grams with p &lt; q.
     *
     * @see Shape#hash
     *
     * @fn Shape#hashNext
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Computes the hash value for the adjacent shape.
     *
     * @signature TValue hashNext(shape, it);
     *
     * @param[in,out] shape Shape to be used for hashing. Types: @link Shape
     *                      @endlink
     * @param[in] it Sequence iterator pointing to the first character of the
     *               adjacent shape.
     *
     * @return TValue Hash value of the q-gram (Metafunction: @link Shape#Value
     *                @endlink).
     *
     * @link Shape#hash @endlink has to be called before.
     *
     * @see Shape#hash
     *
     * @fn Shape#hash2
     *
     * @brief Computes an unique hash value of a shape applied to a sequence, even
     *        if the sequence is shorter than the shape span.
     *
     * @signature TValue hash2(shape, it, charsLeft);
     *
     * @param[in,out] shape Shape to be used for hashing. Types: @link Shape
     *                      @endlink
     * @param[in] it Sequence iterator pointing to the first character of the shape.
     * @param[in] charsLeft The distance of <tt>it</tt> to the string end.
     *
     * @return TValue Hash value of the shape (Metafunction: @link Shape#Value
     *                @endlink).
     *
     * @see Shape#hash2Next
     * @see Shape#hash2Upper
     * @see Shape#unhash
     * @see Shape#hash
     *
     * @fn Shape#hash2Upper
     *
     * @brief Computes an upper unique hash value of a shape applied to a sequence,
     *        even if the sequence is shorter than the shape span.
     *
     * @signature TValue hash2Upper(shape, it, charsLeft);
     *
     * @param[in] shape Shape to be used for hashing. Types: @link Shape @endlink
     * @param[in] it Sequence iterator pointing to the first character of the shape.
     * @param[in] charsLeft The distance of <tt>it</tt> to the string end.
     *
     * @return TValue Upper hash value of the shape. The hash value corresponds to
     *                the maximal @link Shape#hash2 @endlink value of a shape
     *                beginning with the <tt>min(charsLeft,length(shape))</tt>
     *                characters + 1 (Metafunction: @link Shape#Value @endlink).
     *
     * This function in conjunction with @link Shape#hash2 @endlink is useful to
     * search a q-gram index for p-grams with <i>p &lt; q</i>.
     *
     * @see Shape#hash2
     *
     * @fn Shape#hash2Next
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Computes a unique hash value for the adjacent shape, even if it is
     *        shorter than q.
     *
     * @signature TValue hash2Next(shape, it);
     *
     * @param[in,out] shape Shape to be used for hashing the q-gram. Types: @link
     *                      Shape @endlink
     * @param[in,out] it Sequence iterator pointing to the first character of the
     *                   adjacent shape.
     *
     * @return TValue Hash value of the shape (Metafunction: @link Shape#Value
     *                @endlink).
     *
     * @link Shape#hash @endlink has to be called before with <tt>shape</tt> on the
     * left adjacent q-gram.
     *
     * @see Shape#hash2
     *
     * @fn Shape#unhash
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Inverse of the @link Shape#hash @endlink function; for ungapped
     *        shapes.
     *
     * @signature void unhash(result, hash, q);
     *
     * @param[out] result @link String @endlink to write the result to. Types: @link
     *                    String @endlink.
     * @param[in] hash The hash value previously computed with @link Shape#hash
     *                 @endlink.
     * @param[in] q The <tt>q</tt>-gram length. Types: <tt>unsigned</tt>
     *
     * @see Shape#hash
     * @see Shape#hash2
     *
     * @fn Shape#stringToShape
     *
     * @brief Takes a shape given as a string of '1' (relevant position) and '0'
     *        (irrelevant position) and converts it into a Shape object.
     *
     * @signature bool stringToShape(shape, bitmap);
     *
     * @param[in,out] shape Shape object that is manipulated.
     * @param[in] bitmap A character string of '1' and '0' representing relevant and
     *                   irrelevant positions (blanks) respectively. This string
     *                   must begin with a '1'. Trailing '0's are ignored. If
     *                   <tt>shape</tt> is a @link SimpleShape @endlink at most one
     *                   contiguous sequences of <tt>1</tt>s is allowed. If
     *                   <tt>shape</tt> is a @link OneGappedShape @endlink at most
     *                   two contiguous sequences of '1's are allowed (@link String
     *                   @endlink of <tt>char</tt>).
     *
     * @return bool <tt>true</tt> if the conversion was successful.
     *
     * @see Shape#shapeToString
     * @see reverse
     *
     * @fn Shape#shapeToString
     *
     * @brief Converts a given shape into a sequence of '1' (relevant position) and
     *        '0' (irrelevant position).
     *
     * @signature void shapeToString(bitmap, shape);
     *
     * @param[in,out] bitmap The resulting sequence object. Types: @link String
     *                       @endlink
     * @param[in] shape Shape object. Types: @link Shape @endlink
     *
     * @see Shape#stringToShape
     */