/*!
* @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 λ value of the Karlin-Altschul parameters.
*
* @signature double getLambda(blastScoringScheme);
*
* @fn BlastScoringScheme#getKappa
*
* @headerfile <seqan/blast.h>
*
* @brief Get the Κ 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 α value of the Karlin-Altschul parameters.
*
* @signature double getAlpha(blastScoringScheme);
*
* @fn BlastScoringScheme#getBeta
*
* @headerfile <seqan/blast.h>
*
* @brief Get the β 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.
*/