calculateCovariance - SeqAn API Documentation

# fn() calculateCovariance
Calculates the covariance for the number of word occurrences for two words in a sequence of length n, given a background model.

Defined in | <seqan/alignment_free.h>
Signature | `void calculateCovariance(covariance, word1, word2, bgFrequencies, n); void calculateCovariance(covariance, word1, word2, bgModel, n);`

## Parameters

`covariance` | Variance of the number of occurrences of the word in a sequence of length n given the model, `double`.
`word1` | String, usually of Dna.
`word2` | String, usually of Dna.
`bgFrequencies` | String of `double` with the background frequencies representing
`bgModel` | MarkovModel to use.
`n` | Length of the sequence where the occurrences of word are counted, `int`.

## Detailed Description

Calculates the covariance for the number of word occurrences for two words in a sequence of length n given a background model (Markov model or Bernoulli model). The covariance is influenced by the property of words to overlap, for example, the words ATAT and TATA have a high covariance since they are likely to overlap. The formula is based on (Robin et al., 2005).

### References

Robin, S., Rodolphe, F., and Schbath, S. (2005). DNA, Words and Models. Cambridge University Press. See Jonathan Goeke et al (to appear) for details on the implementation.

### Examples

Calculate the covariance for the number of occurrences of ATATAT and TATATA in a sequence of length 10000bp with p(A) = p(T) = 0.3 and p(C) = p(G) = 0.2.

    using namespace seqan2;
    double covar = 0.0;
    int n = 10000;
    DnaString word1 = "ATATAT";
    DnaString word2 = "TATATA";
    String<double> model;
    resize(model, 4);
    model[0] = 0.3;  // p(A)
    model[1] = 0.2;  // p(C)
    model[2] = 0.2;  // p(G)
    model[3] = 0.3;  // p(T)
    calculateCovariance(covar, word1, word2, model, n);  // covar = 4.74

Estimate a Markov model on a set of sequences and calculate the covariance for the number of occurrences of ATATAT and TATATA in a sequence of length 10000bp.

    using namespace seqan2;
    double covar = 0.0;
    int n = 10000;
    DnaString word1 = "ATATAT";
    DnaString word2 = "TATATA";
    StringSet<DnaString> sequences;
    appendValue(sequences, "CAGCACTGATTAACAGGAATAAGCAGTTTACTTCTGTCAGAATATTGGGCATATATA"
                           "CTGGGACCCGTGTAATACTCTAATTTAATTAGGTGATCCCTGCGAAGTCTCCA");
    MarkovModel<Dna, double> modelMM0(0);  // Bernoulli model
    modelMM0.build(sequences);
    calculateCovariance(covar, word1, word2, modelMM0, n);  // covar = 4.74
    MarkovModel<Dna, double> modelMM1(1);  // First order Markov model
    modelMM1.build(sequences);
    calculateCovariance(covar, word1, word2, modelMM1, n);  // covar = 13.1541

## Data Races

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

## See Also

- MarkovModel
- alignmentFreeComparison
- calculateOverlapIndicator
- calculatePeriodicity
- calculateProbability
- calculateVariance
- countKmers

#### Dox Sources

    /*!
     * @fn calculateCovariance
     *
     * @headerfile <seqan/alignment_free.h>
     *
     * @brief Calculates the covariance for the number of word occurrences for two
     *        words in a sequence of length n, given a background model.
     *
     * @signature void calculateCovariance(covariance, word1, word2, bgFrequencies,
     *            n);
     * @signature void calculateCovariance(covariance, word1, word2, bgModel, n);
     *
     * @param[out] covariance Variance of the number of occurrences of the word in a
     *                        sequence of length n given the model, <tt>double</tt>.
     * @param[in] word1 @link String @endlink, usually of Dna.
     * @param[in] word2 @link String @endlink, usually of Dna.
     * @param[in] bgFrequencies @link String @endlink of <tt>double</tt> with the
     *                          background frequencies representing
     * @param[in] bgModel @link MarkovModel @endlink to use.
     * @param[in] n Length of the sequence where the occurrences of word are
     *              counted, <tt>int</tt>.
     *
     * Calculates the covariance for the number of word occurrences for two words in
     * a sequence of length n given a background model (Markov model or Bernoulli
     * model). The covariance is influenced by the property of words to overlap, for
     * example, the words ATAT and TATA have a high covariance since they are likely
     * to overlap. The formula is based on (Robin et al., 2005).
     *
     * @section References
     *
     * Robin, S., Rodolphe, F., and Schbath, S. (2005). DNA, Words and Models.
     * Cambridge University Press. See Jonathan Goeke et al (to appear) for details
     * on the implementation.
     *
     * @section Examples
     *
     * Calculate the covariance for the number of occurrences of ATATAT and TATATA
     * in a sequence of length 10000bp with <i>p(A) = p(T) = 0.3</i> and <i>p(C) =
     * p(G) = 0.2</i>.
     *
     * @code{.cpp}
     * using namespace seqan2;
     * double covar = 0.0;
     * int n = 10000;
     * DnaString word1 = "ATATAT";
     * DnaString word2 = "TATATA";
     * String<double> model;
     * resize(model, 4);
     * model[0] = 0.3;  // p(A)
     * model[1] = 0.2;  // p(C)
     * model[2] = 0.2;  // p(G)
     * model[3] = 0.3;  // p(T)
     * calculateCovariance(covar, word1, word2, model, n);  // covar = 4.74
     * @endcode
     *
     *
     * Estimate a Markov model on a set of sequences and calculate the covariance
     * for the number of occurrences of ATATAT and TATATA in a sequence of length
     * 10000bp.
     *
     * @code{.cpp}
     * using namespace seqan2;
     * double covar = 0.0;
     * int n = 10000;
     * DnaString word1 = "ATATAT";
     * DnaString word2 = "TATATA";
     * StringSet<DnaString> sequences;
     * appendValue(sequences, "CAGCACTGATTAACAGGAATAAGCAGTTTACTTCTGTCAGAATATTGGGCATATATA"
     *                        "CTGGGACCCGTGTAATACTCTAATTTAATTAGGTGATCCCTGCGAAGTCTCCA");
     * MarkovModel<Dna, double> modelMM0(0);  // Bernoulli model
     * modelMM0.build(sequences);
     * calculateCovariance(covar, word1, word2, modelMM0, n);  // covar = 4.74
     * MarkovModel<Dna, double> modelMM1(1);  // First order Markov model
     * modelMM1.build(sequences);
     * calculateCovariance(covar, word1, word2, modelMM1, n);  // covar = 13.1541
     * @endcode
     *
     *
     * @see calculateProbability
     * @see calculateVariance
     * @see MarkovModel
     * @see alignmentFreeComparison
     * @see calculatePeriodicity
     * @see countKmers
     * @see calculateOverlapIndicator
     */