Class BlastScoringScheme

Wrapper around a SeqAn scoring scheme

/*!
 * @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.
 */