HMM Algorithms - SeqAn API Documentation

# Group HMM Algorithms
Algorithms on HmmGraph objects.

## Grouped Function Overview

- `TCargo backwardAlgorithm(hmm, seq);`
  Given a Hidden Markov Model `hmm`, the backward algorithm computes the probability of the sequence `seq`.
- `TCargo forwardAlgorithm(hmm, seq);`
  Given a Hidden Markov Model `hmm`, the forward algorithm computes the probability of the sequence `seq`.
- `void generateSequence(hmm, seq, states, numSeq, maxLen);`
  Generates random state and alphabet sequence of a given HMM.
- `TCargo viterbiAlgorithm(path, hmm, seq);`
  Implements the Viterbi algorithm for Hidden Markov Models.

## Grouped Functions Detail

### `TCargo backwardAlgorithm(hmm, seq);`

Defined in
  <seqan/graph_algorithms.h>

Given a Hidden Markov Model `hmm`, the backward algorithm computes the probability of the sequence `seq`.

#### Parameters

`hmm` | The HmmGraph with the HMM to use.
`seq` | Input sequence to use in the backward algorithm.

#### Returns

`TCargo` | The probability of the sequence `seq`. `TProbability` is the type parameter `TCargo` of the type of `hmm`.

See the Wikipedia article on the Forward-backward algorithm for an introduction to the algorithm itself.

#### Data Races

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

#### See Also

- forwardAlgorithm
- viterbiAlgorithm

### `TCargo forwardAlgorithm(hmm, seq);`

Defined in
  <seqan/graph_algorithms.h>

Given a Hidden Markov Model `hmm`, the forward algorithm computes the probability of the sequence `seq`.

#### Parameters

`hmm` | The HmmGraph with the HMM to use.
`seq` | Input sequence to use in the forward algorithm.

#### Returns

`TProbability` | The probability of the sequence `seq`. `TProbability` is the type parameter `TCargo` of the type of `hmm`.

#### Remarks

See the Wikipedia article on the Forward algorithm for an introduction to the algorithm itself.

#### Data Races

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

#### See Also

- backwardAlgorithm
- viterbiAlgorithm

### `void generateSequence(hmm, seq, states, numSeq, maxLen);`

Defined in
  <seqan/graph_algorithms.h>

Generates random state and alphabet sequence of a given HMM.

#### Parameters

`seq` | A StringSet of alphabet sequences.
`states` | A ContainerConcept object of state sequences.
`hmm` | The HmmGraph to use.
`numSeq` | The number of sequences to generate.
`maxLen` | The maximum length of the sequences. The sequences might be shorter if the ends tate is reached before maxLen.

#### Remarks

Because of silent states, generated alphabet and state sequences might have different lengths.

#### Data Races

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

### `TCargo viterbiAlgorithm(path, hmm, seq);`

Defined in
  <seqan/graph_algorithms.h>

Implements the Viterbi algorithm for Hidden Markov Models.

#### Parameters

`path` | The state path; String of vertex descriptors.
`hmm` | The HmmGraph to use.
`seq` | Input sequence.

#### Returns

`TCargo` | Probability of the path, the type parameter `TCargo` from type of `hmm`.

The Viterbi algorithm computes the most likely sequence of hidden states of the Hidden Markov Model `hmm` given the sequence `seq` using dynamic programming. The result is the most likely sequence of hidden states and returned in `path`.

#### Remarks

See the Wikipedia article on the Viterbi algorithm for an introduction to the algorithm itself.

#### Data Races

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

#### See Also

- backwardAlgorithm
- forwardAlgorithm

#### Dox Sources

    /*!
     * @defgroup HmmAlgorithms HMM Algorithms
     *
     * @brief Algorithms on @link HmmGraph @endlink objects.
     *
     * @fn HmmAlgorithms#viterbiAlgorithm
     *
     * @headerfile <seqan/graph_algorithms.h>
     *
     * @brief Implements the Viterbi algorithm for Hidden Markov Models.
     *
     * @signature TCargo viterbiAlgorithm(path, hmm, seq);
     *
     * @param[out] path The state path; String of vertex descriptors.
     * @param[in] hmm The @link HmmGraph @endlink to use.
     * @param[in] seq Input sequence.
     *
     * @return TCargo Probability of the path, the type parameter <tt>TCargo</tt>
     *                from type of <tt>hmm</tt>.
     *
     * The Viterbi algorithm computes the most likely sequence of hidden states of
     * the Hidden Markov Model <tt>hmm</tt> given the sequence <tt>seq</tt> using
     * dynamic programming. The result is the most likely sequence of hidden states
     * and returned in <tt>path</tt>.
     *
     * @section Remarks
     *
     * See the <a href="https://wikipedia.org/wiki/Viterbi_algorithm"> Wikipedia
     * article on the Viterbi algorithm</a> for an introduction to the algorithm
     * itself.
     *
     * @see HmmAlgorithms#forwardAlgorithm
     * @see HmmAlgorithms#backwardAlgorithm
     *
     * @fn HmmAlgorithms#forwardAlgorithm
     *
     * @headerfile <seqan/graph_algorithms.h>
     *
     * @brief Given a Hidden Markov Model <tt>hmm</tt>, the forward algorithm
     *        computes the probability of the sequence <tt>seq</tt>.
     *
     * @signature TCargo forwardAlgorithm(hmm, seq);
     *
     * @param[in] hmm The @link HmmGraph @endlink with the HMM to use.
     * @param[in] seq Input sequence to use in the forward algorithm.
     *
     * @return TProbability The probability of the sequence <tt>seq</tt>.
     *                      <tt>TProbability</tt> is the type parameter
     *                      <tt>TCargo</tt> of the type of <tt>hmm</tt>.
     *
     * @section Remarks
     *
     * See the <a href="https://en.wikipedia.org/wiki/Forward_algorithm">Wikipedia
     * article on the Forward algorithm</a> for an introduction to the algorithm
     * itself.
     *
     * @see HmmAlgorithms#viterbiAlgorithm
     * @see HmmAlgorithms#backwardAlgorithm
     *
     * @fn HmmAlgorithms#backwardAlgorithm
     *
     * @headerfile <seqan/graph_algorithms.h>
     *
     * @brief Given a Hidden Markov Model <tt>hmm</tt>, the backward algorithm
     *        computes the probability of the sequence <tt>seq</tt>.
     *
     * @signature TCargo backwardAlgorithm(hmm, seq);
     *
     * @param[in] hmm The @link HmmGraph @endlink with the HMM to use.
     * @param[in] seq Input sequence to use in the backward algorithm.
     *
     * @return TCargo The probability of the sequence <tt>seq</tt>.
     *                <tt>TProbability</tt> is the type parameter <tt>TCargo</tt> of
     *                the type of <tt>hmm</tt>.
     *
     * See the <a href="https://en.wikipedia.org/wiki/Forward-
     * backward_algorithm">Wikipedia article on the Forward-backward algorithm</a>
     * for an introduction to the algorithm itself.
     *
     * @see HmmAlgorithms#viterbiAlgorithm
     * @see HmmAlgorithms#forwardAlgorithm
     *
     * @fn HmmAlgorithms#generateSequence
     *
     * @headerfile <seqan/graph_algorithms.h>
     *
     * @brief Generates random state and alphabet sequence of a given HMM.
     *
     * @signature void generateSequence(hmm, seq, states, numSeq, maxLen);
     *
     * @param[out] seq A @link StringSet @endlink of alphabet sequences.
     * @param[out] states A @link ContainerConcept @endlink object of state
     *                    sequences.
     * @param[in] hmm The @link HmmGraph @endlink to use.
     * @param[in] numSeq The number of sequences to generate.
     * @param[in] maxLen The maximum length of the sequences. The sequences might be
     *                   shorter if the ends tate is reached before maxLen.
     *
     * @section Remarks
     *
     * Because of silent states, generated alphabet and state sequences might have
     * different lengths.
     */