Score - SeqAn API Documentation

# Class Score
Scoring scheme.

All Subcl's | EditDistanceScore, MatrixScore, ProfileSeqFracScore, ProfileSeqScore, ScoreSimdWrapper, SimpleScore
Defined in | <seqan/score.h>
Signature | `template <[typename TValue[, typename TSpec]]> class Score;`

## Template Parameters

`TValue` | The scoring value, defaults to `int`.
`TSpec` | The specialization type, defaults to `Simple`.

## Interface Function Overview

- `void loadScoreMatrix(score, fileName[, meta]);`
  Load a score matrix from a file.
- `TValue score(score, entryH, entryV);`
  Returns similarity score for two sequence entries.
- `TValue scoreGapExtendHorizontal(score, entryH, entryV);`
  Returns the score for extending a gap in horizontal direction.
- `TValue scoreGapExtendVertical(score, entryH, entryV);`
  Returns the score for extending a gap in vertical direction.
- `TValue scoreGapHorizontal(score, entryH, entryV);`
  Returns the score for a gap in horizontal direction.
- `TValue scoreGapOpenHorizontal(score, entryH, entryV);`
  Returns the score for opening a gap in horizontal direction.
- `TValue scoreGapOpenVertical(score, entryH, entryV);`
  Returns the score for opening a gap in vertical direction.
- `TValue scoreGapVertical(score, entryH, entryV);`
  Returns the score for a gap in vertical direction.
- `TAlphabet sequenceEntryForScore(scoringScheme, seq, pos);`
  Helper function for element access, depending on score type.

## Interface Metafunction Overview

- `SequenceEntryForScore<TScore, TSequence>::Type;`
  Returns representation type for a character of a position in a sequence.
- `Spec<TScore>::Type;`
  Return the specialization type of the scoring scheme.
- `Value<TScore>::Type;`
  Return the value type of the scoring scheme.

## Detailed Description

The Score class uses similarity scores, i.e. the greater the score value, the greater the similarity. Depending on the exact score, the scores can also be negative for dissimilarity. This choice blends in naturally with the BLOSUM and PAM matrices, for examples. For the edit distance common in computer science, this corresponds to match scores of 0, mismatch and gap scores of -1.

### Examples

    #include <seqan/basic.h>
    #include <seqan/sequence.h>
    #include <seqan/stream.h>  // for I/O
    #include <seqan/align.h>
    #include <seqan/score.h>

    using namespace seqan2;

    int main()
    {
        StringSet<DnaString> stringSet;
        appendValue(stringSet, "ACGTGGATCGGTGACTTACGGACTG");
        appendValue(stringSet, "ACGTGTTGAGTGATTACGGACTG");

        Align<DnaString> align(stringSet);                // Initialize the Align object using a StringSet.

        Score<int> scoreScheme(5, -6, -2, -11);           // Initialize Score object with affine gap costs.
        int score = globalAlignment(align, scoreScheme);  // Computes a global alignment usign the defined scoring scheme.

        std::cout << "Score = " << score << std::endl;
        std::cout << "Alignment:" << std::endl;
        std::cout << align << std::endl;

        return 0;
    }

Demo: demos/dox/score/score.cpp

The output is as follows:

    Score = 66
    Alignment:
          0     .    :    .    :    .
            ACGTG--GATCGGTGACTTACGGACTG
            |||||  ||   |||| ||||||||||
            ACGTGTTGA---GTGA-TTACGGACTG

## Interface Functions Detail

### `void loadScoreMatrix(score, fileName[, meta]);`

Load a score matrix from a file.

#### Parameters

`score` | The MatrixScore to load.
`fileName` | The path to the file to load, CharString.
`meta` | Meta information is stored here, CharString.

#### Data Races

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

### `TValue score(score, entryH, entryV);`

Returns similarity score for two sequence entries.

#### Parameters

`score` | The Score to use for comparing the two sequence entries.
`entryH` | The entry in the first/horizontal sequence.
`entryV` | The entry in the second/vertical sequence.

#### Returns

`TValue` | The score similarity cost for gaps at the given position/entry. TValue is the value type of score.

#### Data Races

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

### `TValue scoreGapExtendHorizontal(score, entryH, entryV);`

Returns the score for extending a gap in horizontal direction.

#### Parameters

`score` | The Score to query.
`entryH` | Entry in sequence one (horizontal), type from Score#SequenceEntryForScore.
`entryV` | Entry in sequence two (vertical), type from Score#SequenceEntryForScore.

#### Returns

`TValue` | The score extension cost for gaps at the given position/entry. TValue is the value type of score.

#### Remarks

Corresponds to a deletion event in sequence two and an insertion event in sequence one, respectively.

#### Data Races

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

### `TValue scoreGapExtendVertical(score, entryH, entryV);`

Returns the score for extending a gap in vertical direction.

#### Parameters

`score` | The Score to query.
`entryH` | Entry in sequence one (horizontal), type from Score#SequenceEntryForScore.
`entryV` | Entry in sequence two (vertical), type from Score#SequenceEntryForScore.

#### Returns

`TValue` | The score extension cost for gaps at the given position/entry. TValue is the value type of score.

#### Remarks

Corresponds to a deletion event in sequence one and an insertion event in sequence two, respectively.

#### Data Races

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

### `TValue scoreGapHorizontal(score, entryH, entryV);`

Returns the score for a gap in horizontal direction.

#### Parameters

`score` | The Score to query.
`entryH` | Entry in sequence one (horizontal), type from Score#SequenceEntryForScore.
`entryV` | Entry in sequence two (vertical), type from Score#SequenceEntryForScore.

#### Returns

`TValue` | The score gap cost for gaps at the given position/entry. TValue is the value type of score.

#### Remarks

Corresponds to a deletion event in sequence two and an insertion event in sequence one, respectively.

#### Data Races

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

### `TValue scoreGapOpenHorizontal(score, entryH, entryV);`

Returns the score for opening a gap in horizontal direction.

#### Parameters

`score` | The Score to query.
`entryH` | Entry in sequence one (horizontal), type from Score#SequenceEntryForScore.
`entryV` | Entry in sequence two (vertical), type from Score#SequenceEntryForScore.

#### Returns

`TValue` | The score open cost for gaps at the given position/entry. TValue is the value type of score.

#### Remarks

Corresponds to a deletion event in sequence two and an insertion event in sequence one, respectively.

#### Data Races

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

### `TValue scoreGapOpenVertical(score, entryH, entryV);`

Returns the score for opening a gap in vertical direction.

#### Parameters

`score` | The Score to query.
`entryH` | Entry in sequence one (horizontal), type from Score#SequenceEntryForScore.
`entryV` | Entry in sequence two (vertical), type from Score#SequenceEntryForScore.

#### Returns

`TValue` | The score open cost for gaps at the given position/entry. TValue is the value type of score.

#### Remarks

Corresponds to a deletion event in sequence two and an insertion event in sequence one, respectively.

#### Data Races

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

### `TValue scoreGapVertical(score, entryH, entryV);`

Returns the score for a gap in vertical direction.

#### Parameters

`score` | The Score to query.
`entryH` | Entry in sequence one (horizontal), type from Score#SequenceEntryForScore.
`entryV` | Entry in sequence two (vertical), type from Score#SequenceEntryForScore.

#### Returns

`TValue` | The score gap cost for gaps at the given position/entry. TValue is the value type of score.

#### Remarks

Corresponds to a deletion event in sequence two and an insertion event in sequence one, respectively.

#### Data Races

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

### `TAlphabet sequenceEntryForScore(scoringScheme, seq, pos);`

Helper function for element access, depending on score type.

#### Parameters

`scoringScheme` | The Score to get the representation for.
`pos` | The position of the character.
`seq` | The sequence to get the representation for.

#### Returns

`TAlphabet` | The value of `seq` at `pos`.

#### Data Races

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

## Interface Metafunctions Detail

### `SequenceEntryForScore<TScore, TSequence>::Type;`

Note.

This is used for unified interfaces for position dependent and independent scores.

Returns representation type for a character of a position in a sequence.

#### Template Parameters

`TScore` | The score type to use. Types: Score
`TSequence` | The underlying sequence of the alignments or gaps. Types: ContainerConcept

#### Returns

`Type` | The type to use for representing a character in a sequence over its position.

### `Spec<TScore>::Type;`

Return the specialization type of the scoring scheme.

#### Template Parameters

`TScore` | The Score specialization.

#### Returns

`Type` | The score specialization type of the scoring scheme.

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

Return the value type of the scoring scheme.

#### Template Parameters

`TScore` | The Score specialization.

#### Returns

`Type` | The score value type of the scoring scheme.

#### Dox Sources

    /*!
     * @class Score
     *
     * @headerfile <seqan/score.h>
     *
     * @brief Scoring scheme.
     *
     * @signature template <[typename TValue[, typename TSpec]]> class Score;
     *
     * @tparam TValue The scoring value, defaults to <tt>int</tt>.
     * @tparam TSpec The specialization type, defaults to <tt>Simple</tt>.
     *
     * The Score class uses <b>similarity</b> scores, i.e. the greater the score
     * value, the greater the similarity. Depending on the exact score, the scores
     * can also be negative for dissimilarity. This choice blends in naturally with
     * the BLOSUM and PAM matrices, for examples. For the edit distance common in
     * computer science, this corresponds to match scores of 0, mismatch and gap
     * scores of -1.
     *
     * @section Examples
     *
     * @include demos/dox/score/score.cpp
     *
     * The output is as follows:
     *
     * @include demos/dox/score/score.cpp.stdout
     *
     *
     *
     * @fn Score#loadScoreMatrix
     *
     * @brief Load a score matrix from a file.
     *
     * @signature void loadScoreMatrix(score, fileName[, meta]);
     *
     * @param[in,out] score The MatrixScore to load.
     * @param[in] fileName The path to the file to load, CharString.
     * @param[out] meta Meta information is stored here, CharString.
     *
     * @fn Score#sequenceEntryForScore
     *
     * @brief Helper function for element access, depending on score type.
     *
     * @signature TAlphabet sequenceEntryForScore(scoringScheme, seq, pos);
     *
     * @param[in] scoringScheme The Score to get the representation for.
     * @param[in] pos The position of the character.
     * @param[in] seq The sequence to get the representation for.
     *
     * @return TAlphabet The value of <tt>seq</tt> at <tt>pos</tt>.
     *
     * @fn Score#scoreGapOpenHorizontal
     *
     * @brief Returns the score for opening a gap in horizontal direction.
     *
     * @signature TValue scoreGapOpenHorizontal(score, entryH, entryV);
     *
     * @param[in] score The Score to query.
     * @param[in] entryH Entry in sequence one (horizontal), type from
     *                   Score#SequenceEntryForScore.
     * @param[in] entryV Entry in sequence two (vertical), type from
     *                   Score#SequenceEntryForScore.
     *
     * @return TValue The score open cost for gaps at the given position/entry.
     *                TValue is the value type of score.
     *
     * @section Remarks
     *
     * Corresponds to a deletion event in sequence two and an insertion event in
     * sequence one, respectively.
     *
     * @fn Score#scoreGapOpenVertical
     *
     * @brief Returns the score for opening a gap in vertical direction.
     *
     * @signature TValue scoreGapOpenVertical(score, entryH, entryV);
     *
     * @param[in] score The Score to query.
     * @param[in] entryH Entry in sequence one (horizontal), type from
     *                   Score#SequenceEntryForScore.
     * @param[in] entryV Entry in sequence two (vertical), type from
     *                   Score#SequenceEntryForScore.
     *
     * @return TValue The score open cost for gaps at the given position/entry.
     *                TValue is the value type of score.
     *
     * @section Remarks
     *
     * Corresponds to a deletion event in sequence two and an insertion event in
     * sequence one, respectively.
     *
     * @fn Score#scoreGapExtendHorizontal
     *
     * @brief Returns the score for extending a gap in horizontal direction.
     *
     * @signature TValue scoreGapExtendHorizontal(score, entryH, entryV);
     *
     * @param[in] score The Score to query.
     * @param[in] entryH Entry in sequence one (horizontal), type from
     *                   Score#SequenceEntryForScore.
     * @param[in] entryV Entry in sequence two (vertical), type from
     *                   Score#SequenceEntryForScore.
     *
     * @return TValue The score extension cost for gaps at the given position/entry.
     *                TValue is the value type of score.
     *
     * @section Remarks
     *
     * Corresponds to a deletion event in sequence two and an insertion event in
     * sequence one, respectively.
     *
     * @fn Score#scoreGapExtendVertical
     *
     * @brief Returns the score for extending a gap in vertical direction.
     *
     * @signature TValue scoreGapExtendVertical(score, entryH, entryV);
     *
     * @param[in] score The Score to query.
     * @param[in] entryH Entry in sequence one (horizontal), type from
     *                   Score#SequenceEntryForScore.
     * @param[in] entryV Entry in sequence two (vertical), type from
     *                   Score#SequenceEntryForScore.
     *
     * @return TValue The score extension cost for gaps at the given position/entry.
     *                TValue is the value type of score.
     *
     * @section Remarks
     *
     * Corresponds to a deletion event in sequence one and an insertion event in
     * sequence two, respectively.
     *
     * @fn Score#scoreGapHorizontal
     *
     * @brief Returns the score for a gap in horizontal direction.
     *
     * @signature TValue scoreGapHorizontal(score, entryH, entryV);
     *
     * @param[in] score The Score to query.
     * @param[in] entryH Entry in sequence one (horizontal), type from
     *                   Score#SequenceEntryForScore.
     * @param[in] entryV Entry in sequence two (vertical), type from
     *                   Score#SequenceEntryForScore.
     *
     * @return TValue The score gap cost for gaps at the given position/entry.
     *                TValue is the value type of score.
     *
     * @section Remarks
     *
     * Corresponds to a deletion event in sequence two and an insertion event in
     * sequence one, respectively.
     *
     * @fn Score#scoreGapVertical
     *
     * @brief Returns the score for a gap in vertical direction.
     *
     * @signature TValue scoreGapVertical(score, entryH, entryV);
     *
     * @param[in] score The Score to query.
     * @param[in] entryH Entry in sequence one (horizontal), type from
     *                   Score#SequenceEntryForScore.
     * @param[in] entryV Entry in sequence two (vertical), type from
     *                   Score#SequenceEntryForScore.
     *
     * @return TValue The score gap cost for gaps at the given position/entry.
     *                TValue is the value type of score.
     *
     * @section Remarks
     *
     * Corresponds to a deletion event in sequence two and an insertion event in
     * sequence one, respectively.
     *
     * @fn Score#score
     *
     * @brief Returns similarity score for two sequence entries.
     *
     * @signature TValue score(score, entryH, entryV);
     *
     * @param[in] score The Score to use for comparing the two sequence entries.
     * @param[in] entryH The entry in the first/horizontal sequence.
     * @param[in] entryV The entry in the second/vertical sequence.
     *
     * @return TValue The score similarity cost for gaps at the given
     *                position/entry. TValue is the value type of score.
     *
     * @mfn Score#Value
     *
     * @brief Return the value type of the scoring scheme.
     *
     * @signature Value<TScore>::Type;
     *
     * @tparam TScore The Score specialization.
     *
     * @return Type The score value type of the scoring scheme.
     *
     * @mfn Score#Spec
     *
     * @brief Return the specialization type of the scoring scheme.
     *
     * @signature Spec<TScore>::Type;
     *
     * @tparam TScore The Score specialization.
     *
     * @return Type The score specialization type of the scoring scheme.
     *
     * @mfn Score#SequenceEntryForScore
     *
     * @headerfile <seqan/score.h>
     *
     * @brief Returns representation type for a character of a position in a
     *        sequence.
     *
     * @note This is used for unified interfaces for position dependent and
     *       independent scores.
     *
     * @signature SequenceEntryForScore<TScore, TSequence>::Type;
     *
     * @tparam TScore The score type to use. Types: Score
     * @tparam TSequence The underlying sequence of the alignments or gaps. Types:
     *                   ContainerConcept
     *
     * @return Type The type to use for representing a character in a sequence over
     *              its position.
     *
     * @see Score#SequenceEntryForScore
     * @see Score#sequenceEntryForScore
     * @see ConsensusScoreSequenceEntry
     */