BlastScoringScheme - SeqAn API Documentation

# Class BlastScoringScheme
Wrapper around a SeqAn scoring scheme

Defined in | <seqan/blast.h>
Signature | `struct BlastScoringScheme<TScoringScheme> { ... };`

## Template Parameters

`TScoringScheme` | A SeqAn Score type

## Interface Function Overview

- `double computeBitScore(rawScore, blastScoringScheme);`
  Compute the bit-score for a given raw score.
- `double computeEValue(rawScore, queryLength, dbLength, blastScoringScheme);`
  Compute the E-Value for a given raw score and sequence lengths.
- `double getAlpha(blastScoringScheme);`
  Get the α value of the Karlin-Altschul parameters.
- `double getBeta(blastScoringScheme);`
  Get the β value of the Karlin-Altschul parameters.
- `double getH(blastScoringScheme);`
  Get the H value of the Karlin-Altschul parameters.
- `double getKappa(blastScoringScheme);`
  Get the Κ value of the Karlin-Altschul parameters.
- `double getLambda(blastScoringScheme);`
  Get the λ value of the Karlin-Altschul parameters.
- `bool isValid(blastScoringScheme);`
  check whether valid KarlinAltschulValues are selected
- `TValue scoreGapExtend(blastScoringScheme);`
  The Gap Extend score.
- `TValue scoreGapOpen(blastScoringScheme);`
  The Gap Open score in SeqAn convention.
- `TValue scoreGapOpenBlast(blastScoringScheme);`
  The Gap Open score in Blast convention.
- `int scoreMatch(blastScoringScheme);`
  The Match score (only for SimpleScore specialization).
- `int scoreMismatch(blastScoringScheme);`
  The Mismatch score (only for SimpleScore specialization).
- `TScoringScheme const & seqanScheme(blastScoringScheme);`
  Retrieve a Score object for use with e.g. localAlignment.
- `bool setScoreGapExtend(blastScoringScheme, value);`
  Set gap extend score.
- `bool setScoreGapOpen(blastScoringScheme, value);`
  Set gap open score in SeqAn convention.
- `bool setScoreGapOpenBlast(blastScoringScheme, value);`
  Set gap open score in BLAST convention.
- `bool setScoreMatch(blastScoringScheme, value);`
  Set match score.
- `bool setScoreMismatch(blastScoringScheme, value);`
  Set mismatch score.

## Detailed Description

This class wraps around a SeqAn scoring scheme and add functions for the retrievel of pre-computed Karlin-Altschul-Values (required for e-value statistics) and it modifies the gap-scoring slightly. If you use high-level IO (BlastReport, BlastTabular) you need not worry about the specifics, however you should always make sure that the scoring scheme isValid after you modify it (or check the return values of the set* functions).

To retrieve a score-object compatible with regular SeqAn-functions, call seqanScheme.

### Gap cost computation

Gap-costs are computed differently in SeqAn and in BLAST. Blast (and many other tools) compute scores of a stretch of gaps as `s = gO + n * gE` where gO is the gapOpen score, gE is the gap extend score and n ist the total number of gap characters.

SeqAn, however, normally computes them as as `s = gO + (n-1) * gE`.

Effectively this results only in a different gap open score. To make dealing with this easier, there are convenience functions for setting and getting the gap open score in blast convention: scoreGapOpenBlast and setScoreGapOpenBlast.

### Karlin-Altschul values

E-Value statistics require certain pre-computed constants. The BlastScoringScheme picks these automatically whenever you modify it. Unfortunately there aren't parameters for all combinations of scoring schemes and gap costs, so you have to check isValid after modifying it or verify the return value of the set* functions which is bool here (instead of void).

More details on the scoring parameters is in these slides: https://www.cs.umd.edu/class/fall2011/cmsc858s/Local_Alignment_Statistics.pdf.

The constants used in SeqAn were imported from the NCBI blast source code (blast-2.2.26)

## Interface Functions Detail

### `double computeBitScore(rawScore, blastScoringScheme);`

Compute the bit-score for a given raw score.

#### Parameters

`rawScore` | The raw score of the alignment.
`blastScoringScheme` | The BlastScoringScheme.

#### Returns

`double` | The bit-score computed.

#### Data Races

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

### `double computeEValue(rawScore, queryLength, dbLength, blastScoringScheme);`

Compute the E-Value for a given raw score and sequence lengths.

#### Parameters

`rawScore` | The raw score of the alignment.
`queryLength` | The length of the query sequence.
`dbLength` | The length of the database in case of many subject sequences, otherwise the length of the subject sequence.
`blastScoringScheme` | The BlastScoringScheme.

#### Returns

`double` | The e-value computed.

#### Data Races

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

### `double getAlpha(blastScoringScheme);`

Get the α value of the Karlin-Altschul parameters.

#### Data Races

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

### `double getBeta(blastScoringScheme);`

Get the β value of the Karlin-Altschul parameters.

#### Data Races

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

### `double getH(blastScoringScheme);`

Get the H value of the Karlin-Altschul parameters.

#### Data Races

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

### `double getKappa(blastScoringScheme);`

Get the Κ value of the Karlin-Altschul parameters.

#### Data Races

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

### `double getLambda(blastScoringScheme);`

Get the λ value of the Karlin-Altschul parameters.

#### Data Races

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

### `bool isValid(blastScoringScheme);`

check whether valid KarlinAltschulValues are selected

#### Data Races

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

### `TValue scoreGapExtend(blastScoringScheme);`

The Gap Extend score.

#### Data Races

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

### `TValue scoreGapOpen(blastScoringScheme);`

The Gap Open score in SeqAn convention.

#### Data Races

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

### `TValue scoreGapOpenBlast(blastScoringScheme);`

The Gap Open score in Blast convention.

#### Data Races

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

### `int scoreMatch(blastScoringScheme);`

The Match score (only for SimpleScore specialization).

#### Data Races

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

### `int scoreMismatch(blastScoringScheme);`

The Mismatch score (only for SimpleScore specialization).

#### Data Races

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

### `TScoringScheme const & seqanScheme(blastScoringScheme);`

Retrieve a Score object for use with e.g. localAlignment.

#### Returns

`TScoringScheme_const_&` | the internal scoring object for use with other SeqAn functions.

#### Remarks

The reference returned is always const, because you should not modify the internal score object directly. Use BlastScoringScheme's interface instead.

#### Data Races

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

### `bool setScoreGapExtend(blastScoringScheme, value);`

Set gap extend score.

#### Parameters

`blastScoringScheme` | The BlastScoringScheme to modify.
`value` | The new value.

#### Returns

`isValid(blastScoringScheme)` | whether Karlin-Altschul values for the new scheme exist.

#### Data Races

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

### `bool setScoreGapOpen(blastScoringScheme, value);`

Set gap open score in SeqAn convention.

#### Parameters

`blastScoringScheme` | The BlastScoringScheme to modify.
`value` | The new value.

#### Returns

`isValid(blastScoringScheme)` | whether Karlin-Altschul values for the new scheme exist.

#### Data Races

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

### `bool setScoreGapOpenBlast(blastScoringScheme, value);`

Set gap open score in BLAST convention.

#### Parameters

`blastScoringScheme` | The BlastScoringScheme to modify.
`value` | The new value.

#### Returns

`isValid(blastScoringScheme)` | whether Karlin-Altschul values for the new scheme exist.

#### Data Races

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

### `bool setScoreMatch(blastScoringScheme, value);`

Set match score.

#### Parameters

`blastScoringScheme` | The BlastScoringScheme to modify.
`value` | The new value.

#### Returns

`isValid(blastScoringScheme)` | whether Karlin-Altschul values for the new scheme exist.

#### Data Races

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

### `bool setScoreMismatch(blastScoringScheme, value);`

Set mismatch score.

#### Parameters

`blastScoringScheme` | The BlastScoringScheme to modify.
`value` | The new value.

#### Returns

`isValid(blastScoringScheme)` | whether Karlin-Altschul values for the new scheme exist.

#### Data Races

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

#### Dox Sources

    /*!
     * @class BlastScoringScheme
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Wrapper around a SeqAn scoring scheme
     *
     * @signature struct BlastScoringScheme<TScoringScheme> { ... };
     *
     * @tparam TScoringScheme A SeqAn Score type
     *
     * This class wraps around a SeqAn scoring scheme and add functions for the
     * retrievel of pre-computed Karlin-Altschul-Values (required for e-value
     * statistics) and it modifies the gap-scoring slightly. If you use high-level
     * IO (@link BlastReport @endlink, @link BlastTabular @endlink) you need not
     * worry about the specifics, however you should always make sure that the
     * scoring scheme @link BlastScoringScheme#isValid @endlink after you modify it
     * (or check the return values of the set* functions).
     *
     * To retrieve a score-object compatible with regular SeqAn-functions, call
     * @link BlastScoringScheme#seqanScheme @endlink.
     *
     * @section Gap cost computation
     *
     * Gap-costs are computed differently in SeqAn and in BLAST. Blast (and many
     * other tools) compute scores of a stretch of gaps as <tt>s = gO + n * gE</tt>
     * where gO is the gapOpen score, gE is the gap extend score and n ist the total
     * number of gap characters.
     *
     * SeqAn, however, normally computes them as as <tt>s = gO + (n-1) * gE</tt>.
     *
     * Effectively this results only in a different gap open score. To make dealing
     * with this easier, there are convenience functions for setting and getting the
     * gap open score in blast convention: @link
     * BlastScoringScheme#scoreGapOpenBlast @endlink and @link
     * BlastScoringScheme#setScoreGapOpenBlast @endlink.
     *
     * @section Karlin-Altschul values
     *
     * E-Value statistics require certain pre-computed constants. The
     * BlastScoringScheme picks these automatically whenever you modify it.
     * Unfortunately there aren't parameters for all combinations of scoring schemes
     * and gap costs, so you have to check @link BlastScoringScheme#isValid @endlink
     * after modifying it or verify the return value of the set* functions which is
     * bool here (instead of void).
     *
     * More details on the scoring parameters is in these slides: <a href="https://w
     * ww.cs.umd.edu/class/fall2011/cmsc858s/Local_Alignment_Statistics.pdf"> https:
     * //www.cs.umd.edu/class/fall2011/cmsc858s/Local_Alignment_Statistics.pdf</a>.
     *
     * The constants used in SeqAn were imported from the NCBI blast source code
     * (blast-2.2.26)
     *
     * @fn BlastScoringScheme#seqanScheme
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Retrieve a @link Score @endlink object for use with e.g. @link
     *        localAlignment @endlink.
     *
     * @signature TScoringScheme const & seqanScheme(blastScoringScheme);
     *
     * @return TScoringScheme_const_& the internal scoring object for use with other
     *                                SeqAn functions.
     *
     * @section Remarks
     *
     * The reference returned is always const, because you should not modify the
     * internal score object directly. Use @link BlastScoringScheme @endlink's
     * interface instead.
     *
     * @fn BlastScoringScheme#scoreMatch
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief The Match score (only for SimpleScore specialization).
     *
     * @signature int scoreMatch(blastScoringScheme);
     *
     * @fn BlastScoringScheme#scoreMismatch
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief The Mismatch score (only for SimpleScore specialization).
     *
     * @signature int scoreMismatch(blastScoringScheme);
     *
     * @fn BlastScoringScheme#scoreGapOpen
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief The Gap Open score in SeqAn convention.
     *
     * @signature TValue scoreGapOpen(blastScoringScheme);
     *
     * @fn BlastScoringScheme#scoreGapOpenBlast
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief The Gap Open score in Blast convention.
     *
     * @signature TValue scoreGapOpenBlast(blastScoringScheme);
     *
     * @fn BlastScoringScheme#scoreGapExtend
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief The Gap Extend score.
     *
     * @signature TValue scoreGapExtend(blastScoringScheme);
     *
     * @fn BlastScoringScheme#isValid
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief check whether valid KarlinAltschulValues are selected
     *
     * @signature bool isValid(blastScoringScheme);
     *
     * @fn BlastScoringScheme#setScoreMatch
     *
     * @brief Set match score.
     *
     * @signature bool setScoreMatch(blastScoringScheme, value);
     *
     * @param[in,out] blastScoringScheme The @link BlastScoringScheme @endlink to
     *                                   modify.
     * @param[in] value The new value.
     *
     * @return isValid(blastScoringScheme) whether Karlin-Altschul values for the
     *                                     new scheme exist.
     *
     * @fn BlastScoringScheme#setScoreMismatch
     *
     * @brief Set mismatch score.
     *
     * @signature bool setScoreMismatch(blastScoringScheme, value);
     *
     * @param[in,out] blastScoringScheme The @link BlastScoringScheme @endlink to
     *                                   modify.
     * @param[in] value The new value.
     *
     * @return isValid(blastScoringScheme) whether Karlin-Altschul values for the
     *                                     new scheme exist.
     *
     * @fn BlastScoringScheme#setScoreGapOpenBlast
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Set gap open score in BLAST convention.
     *
     * @signature bool setScoreGapOpenBlast(blastScoringScheme, value);
     *
     * @param[in,out] blastScoringScheme The @link BlastScoringScheme @endlink to
     *                                   modify.
     * @param[in] value The new value.
     *
     * @return isValid(blastScoringScheme) whether Karlin-Altschul values for the
     *                                     new scheme exist.
     *
     * @fn BlastScoringScheme#setScoreGapOpen
     *
     * @brief Set gap open score in SeqAn convention.
     *
     * @signature bool setScoreGapOpen(blastScoringScheme, value);
     *
     * @param[in,out] blastScoringScheme The @link BlastScoringScheme @endlink to
     *                                   modify.
     * @param[in] value The new value.
     *
     * @return isValid(blastScoringScheme) whether Karlin-Altschul values for the
     *                                     new scheme exist.
     *
     * @fn BlastScoringScheme#setScoreGapExtend
     *
     * @brief Set gap extend score.
     *
     * @signature bool setScoreGapExtend(blastScoringScheme, value);
     *
     * @param[in,out] blastScoringScheme The @link BlastScoringScheme @endlink to
     *                                   modify.
     * @param[in] value The new value.
     *
     * @return isValid(blastScoringScheme) whether Karlin-Altschul values for the
     *                                     new scheme exist.
     *
     * @fn BlastScoringScheme#getLambda
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Get the &lambda; value of the Karlin-Altschul parameters.
     *
     * @signature double getLambda(blastScoringScheme);
     *
     * @fn BlastScoringScheme#getKappa
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Get the &Kappa; value of the Karlin-Altschul parameters.
     *
     * @signature double getKappa(blastScoringScheme);
     *
     * @fn BlastScoringScheme#getH
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Get the H value of the Karlin-Altschul parameters.
     *
     * @signature double getH(blastScoringScheme);
     *
     * @fn BlastScoringScheme#getAlpha
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Get the &alpha; value of the Karlin-Altschul parameters.
     *
     * @signature double getAlpha(blastScoringScheme);
     *
     * @fn BlastScoringScheme#getBeta
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Get the &beta; value of the Karlin-Altschul parameters.
     *
     * @signature double getBeta(blastScoringScheme);
     *
     * @fn BlastScoringScheme#computeBitScore
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Compute the bit-score for a given raw score.
     *
     * @signature double computeBitScore(rawScore, blastScoringScheme);
     *
     * @param[in] rawScore The raw score of the alignment.
     * @param[in] blastScoringScheme The @link BlastScoringScheme @endlink.
     *
     * @return double The bit-score computed.
     *
     * @fn BlastScoringScheme#computeEValue
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Compute the E-Value for a given raw score and sequence lengths.
     *
     * @signature double computeEValue(rawScore, queryLength, dbLength,
     *            blastScoringScheme);
     *
     * @param[in] rawScore The raw score of the alignment.
     * @param[in] queryLength The length of the query sequence.
     * @param[in] dbLength The length of the database in case of many subject
     *                     sequences, otherwise the length of the subject sequence.
     * @param[in] blastScoringScheme The @link BlastScoringScheme @endlink.
     *
     * @return double The e-value computed.
     */