Predicting various Thermodynamic Properties — ViennaRNA Package

# Predicting various Thermodynamic Properties

Compute various thermodynamic properties using the partition function.

Many thermodynamic properties can be derived from the partition function

\[Z = \sum_{s \in \omega} e^{\frac{-E(s)}{kT}}.\]

In particular, for nucleic acids in equilibrium the probabilty \(p(F)\) of a particular structural feature \(F\) follows Boltzmanns law, i.e.:

\[p(F) \propto \sum_{s \mid F \in s} e^{\frac{-E(s)}{kT}}.\]

The actual probabilities can then be obtained from the ratio of those structures containing \(F\) and all structures, i.e.

\[p(F) = \frac{1}{Z} \sum_{s \mid F \in s} e^{\frac{-E(s)}{kT}}.\]

Consequently, a particular secondary structure \(s\) has equilibrium probability

\[p(s) = \frac{1}{Z} e^{\frac{-E(s)}{kT}}\]

which can be easily computed once \(Z\) and \(E(s)\) are known.

Efficient dynamic programming algorithms exist to compute the equilibrium probabilities

\[p_{ij} = \frac{1}{Z} \sum_{s \mid (i,j) \in s} e^{\frac{-E(s)}{kT}}\]

of base pairs \((i,j)\) without the need for exhaustive enumeration of \(s\).

This interface provides the functions for all thermodynamic property computations implemented in RNAlib.

## Thermodynamic Properties API

  Basic heat capacity function interface

  vrna_heat_capacity_t *vrna_heat_capacity(vrna_fold_compound_t *fc, float T_min, float T_max, float T_increment, unsigned int mpoints)

    Compute the specific heat for an RNA.

        #include <ViennaRNA/heat_capacity.h>

    This function computes an RNAs specific heat in a given temperature range from the partition function by numeric differentiation. The result is returned as a list of pairs of temperature in °C and specific heat in Kcal/(Mol*K).

    Users can specify the temperature range for the computation from `T_min` to `T_max`, as well as the increment step size `T_increment`. The latter also determines how many times the partition function is computed. Finally, the parameter `mpoints` determines how smooth the curve should be. The algorithm itself fits a parabola to \( 2 \cdot mpoints + 1 \) data points to calculate 2nd derivatives. Increasing this parameter produces a smoother curve.

    SWIG Wrapper Notes:

      This function is attached as overloaded method `heat_capacity()` to objects of type `fold_compound`. If the optional function arguments `T_min`, `T_max`, `T_increment`, and `mpoints` are omitted, they default to 0.0, 100.0, 1.0 and 2, respectively. See, e.g. `RNA.fold_compound.heat_capacity()` in the Python API.

    See also

    vrna_heat_capacity_cb(), vrna_heat_capacity_t, vrna_heat_capacity_s

    Parameters:

      - fc – The vrna_fold_compound_t with the RNA sequence to analyze

      - T_min – Lowest temperature in °C

      - T_max – Highest temperature in °C

      - T_increment – Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C)

      - mpoints – The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100)

    Returns:

      A list of pairs of temperatures and corresponding heat capacity or NULL upon any failure. The last entry of the list is indicated by a temperature field set to a value smaller than `T_min`

  int vrna_heat_capacity_cb(vrna_fold_compound_t *fc, float T_min, float T_max, float T_increment, unsigned int mpoints, vrna_heat_capacity_f cb, void *data)

    Compute the specific heat for an RNA (callback variant).

        #include <ViennaRNA/heat_capacity.h>

    Similar to vrna_heat_capacity(), this function computes an RNAs specific heat in a given temperature range from the partition function by numeric differentiation. Instead of returning a list of temperature/specific heat pairs, however, this function returns the individual results through a callback mechanism. The provided function will be called for each result and passed the corresponding temperature and specific heat values along with the arbitrary data as provided through the `data` pointer argument.

    Users can specify the temperature range for the computation from `T_min` to `T_max`, as well as the increment step size `T_increment`. The latter also determines how many times the partition function is computed. Finally, the parameter `mpoints` determines how smooth the curve should be. The algorithm itself fits a parabola to \( 2 \cdot mpoints + 1 \) data points to calculate 2nd derivatives. Increasing this parameter produces a smoother curve.

    SWIG Wrapper Notes:

      This function is attached as method `heat_capacity_cb()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.heat_capacity_cb()` in the Python API.

    See also

    vrna_heat_capacity(), vrna_heat_capacity_f

    Parameters:

      - fc – The vrna_fold_compound_t with the RNA sequence to analyze

      - T_min – Lowest temperature in °C

      - T_max – Highest temperature in °C

      - T_increment – Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C)

      - mpoints – The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100)

      - cb – The user-defined callback function that receives the individual results

      - data – An arbitrary data structure that will be passed to the callback in conjunction with the results

    Returns:

      Returns 0 upon failure, and non-zero otherwise

  Simplified heat capacity computation

  vrna_heat_capacity_t *vrna_heat_capacity_simple(const char *sequence, float T_min, float T_max, float T_increment, unsigned int mpoints)

    Compute the specific heat for an RNA (simplified variant).

        #include <ViennaRNA/heat_capacity.h>

    Similar to vrna_heat_capacity(), this function computes an RNAs specific heat in a given temperature range from the partition function by numeric differentiation. This simplified version, however, only requires the RNA sequence as input instead of a vrna_fold_compound_t data structure. The result is returned as a list of pairs of temperature in °C and specific heat in Kcal/(Mol*K).

    Users can specify the temperature range for the computation from `T_min` to `T_max`, as well as the increment step size `T_increment`. The latter also determines how many times the partition function is computed. Finally, the parameter `mpoints` determines how smooth the curve should be. The algorithm itself fits a parabola to \( 2 \cdot mpoints + 1 \) data points to calculate 2nd derivatives. Increasing this parameter produces a smoother curve.

    SWIG Wrapper Notes:

      This function is available as overloaded function `heat_capacity()`. If the optional function arguments `T_min`, `T_max`, `T_increment`, and `mpoints` are omitted, they default to 0.0, 100.0, 1.0 and 2, respectively. See, e.g. `RNA.head_capacity()` in the Python API.

    See also

    vrna_heat_capacity(), vrna_heat_capacity_cb(), vrna_heat_capacity_t, vrna_heat_capacity_s

    Parameters:

      - sequence – The RNA sequence input (must be uppercase)

      - T_min – Lowest temperature in °C

      - T_max – Highest temperature in °C

      - T_increment – Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C)

      - mpoints – The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100)

    Returns:

      A list of pairs of temperatures and corresponding heat capacity or NULL upon any failure. The last entry of the list is indicated by a temperature field set to a value smaller than `T_min`

  Base pair probabilities and derived computations

  int vrna_pairing_probs(vrna_fold_compound_t *fc, char *structure)

        #include <ViennaRNA/probabilities/basepairs.h>

  vrna_ep_t *vrna_stack_prob(vrna_fold_compound_t *fc, double cutoff)

    Compute stacking probabilities.

        #include <ViennaRNA/probabilities/basepairs.h>

    For each possible base pair \((i,j)\), compute the probability of a stack \((i,j)\), \((i+1, j-1)\).

    SWIG Wrapper Notes:

      This function is attached as overloaded method `stack_prob()` to objects of type `fold_compound`. The optional argument `cutoff` defaults to 1e-5. See, e.g. `RNA.fold_compound.stack_prob()` in the Python API.

    Parameters:

      - fc – The fold compound data structure with precomputed base pair probabilities

      - cutoff – A cutoff value that limits the output to stacks with \( p > \textrm{cutoff} \).

    Returns:

      A list of stacks with enclosing base pair \((i,j)\) and probabiltiy \( p \)

  Multimer probabilities computations

  void vrna_pf_dimer_probs(double FAB, double FA, double FB, vrna_ep_t *prAB, const vrna_ep_t *prA, const vrna_ep_t *prB, int Alength, const vrna_exp_param_t *exp_params)

    Compute Boltzmann probabilities of dimerization without homodimers.

        #include <ViennaRNA/probabilities/basepairs.h>

    Given the pair probabilities and free energies (in the null model) for a dimer AB and the two constituent monomers A and B, compute the conditional pair probabilities given that a dimer AB actually forms. Null model pair probabilities are given as a list as produced by vrna_plist_from_probs(), the dimer probabilities ‘prAB’ are modified in place.

    Parameters:

      - FAB – free energy of dimer AB

      - FA – free energy of monomer A

      - FB – free energy of monomer B

      - prAB – pair probabilities for dimer

      - prA – pair probabilities monomer

      - prB – pair probabilities monomer

      - Alength – Length of molecule A

      - exp_params – The precomputed Boltzmann factors

  Structure probability computations

  double vrna_mean_bp_distance_pr(int length, FLT_OR_DBL *pr)

    Get the mean base pair distance in the thermodynamic ensemble from a probability matrix.

        #include <ViennaRNA/probabilities/structures.h>

    \[<d> = \sum_{a,b} p_a p_b d(S_a,S_b) \]

    this can be computed from the pair probs \( p_{ij} \) as

    \[<d> = \sum_{ij} p_{ij}(1-p_{ij}) \]
    Parameters:

      - length – The length of the sequence

      - pr – The matrix containing the base pair probabilities

    Returns:

      The mean pair distance of the structure ensemble

  double vrna_mean_bp_distance(vrna_fold_compound_t *fc)

    Get the mean base pair distance in the thermodynamic ensemble.

        #include <ViennaRNA/probabilities/structures.h>

    \[<d> = \sum_{a,b} p_a p_b d(S_a,S_b) \]

    this can be computed from the pair probs \(p_{ij}\) as

    \[<d> = \sum_{ij} p_{ij}(1-p_{ij}) \]

    SWIG Wrapper Notes:

      This function is attached as method `mean_bp_distance()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.mean_bp_distance()` in the Python API.

    Parameters:

      - fc – The fold compound data structure

    Returns:

      The mean pair distance of the structure ensemble

  double vrna_ensemble_defect_pt(vrna_fold_compound_t *fc, const short *pt)

    Compute the Ensemble Defect for a given target structure provided as a vrna_ptable.

        #include <ViennaRNA/probabilities/structures.h>

    Given a target structure \(s\), compute the average dissimilarity of a randomly drawn structure from the ensemble, i.e.:

    \[ ED(s) = 1 - \frac{1}{n} \sum_{ij, (i,j) \in s} p_{ij} - \frac{1}{n} \sum_{i}(1 - s_i)q_i \]

    with sequence length \(n\), the probability \(p_{ij}\) of a base pair \((i,j)\), the probability \(q_i = 1 - \sum_j p_{ij}\) of nucleotide \(i\) being unpaired, and the indicator variable \(s_i = 1\) if \(\exists (i,j) \in s\), and \(s_i = 0\) otherwise.

    SWIG Wrapper Notes:

      This function is attached as overloaded method `ensemble_defect()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.ensemble_defect()` in the Python API.

    See also

    vrna_pf(), vrna_pairing_probs(), vrna_ensemble_defect()

    Parameters:

      - fc – A fold_compound with pre-computed base pair probabilities

      - pt – A pair table representing a target structure

    Pre:

      The vrna_fold_compound_t input parameter `fc` must contain a valid base pair probability matrix. This means that partition function and base pair probabilities must have been computed using `fc` before execution of this function!

    Returns:

      The ensemble defect with respect to the target structure, or -1. upon failure, e.g. pre-conditions are not met

  double vrna_ensemble_defect(vrna_fold_compound_t *fc, const char *structure)

    Compute the Ensemble Defect for a given target structure.

        #include <ViennaRNA/probabilities/structures.h>

    This is a wrapper around vrna_ensemble_defect_pt(). Given a target structure \(s\), compute the average dissimilarity of a randomly drawn structure from the ensemble, i.e.:

    \[ ED(s) = 1 - \frac{1}{n} \sum_{ij, (i,j) \in s} p_{ij} - \frac{1}{n} \sum_{i}(1 - s_i)q_i \]

    with sequence length \(n\), the probability \(p_{ij}\) of a base pair \((i,j)\), the probability \(q_i = 1 - \sum_j p_{ij}\) of nucleotide \(i\) being unpaired, and the indicator variable \(s_i = 1\) if \(\exists (i,j) \in s\), and \(s_i = 0\) otherwise.

    SWIG Wrapper Notes:

      This function is attached as method `ensemble_defect()` to objects of type `fold_compound`. Note that the SWIG wrapper takes a structure in dot-bracket notation and converts it into a pair table using vrna_ptable_from_string(). The resulting pair table is then internally passed to vrna_ensemble_defect_pt(). To control which kind of matching brackets will be used during conversion, the optional argument `options` can be used. See also the description of vrna_ptable_from_string() for available options. (default: `VRNA_BRACKETS_RND`). See, e.g. `RNA.fold_compound.ensemble_defect()` in the Python API.

    See also

    vrna_pf(), vrna_pairing_probs(), vrna_ensemble_defect_pt()

    Parameters:

      - fc – A fold_compound with pre-computed base pair probabilities

      - structure – A target structure in dot-bracket notation

    Pre:

      The vrna_fold_compound_t input parameter `fc` must contain a valid base pair probability matrix. This means that partition function and base pair probabilities must have been computed using `fc` before execution of this function!

    Returns:

      The ensemble defect with respect to the target structure, or -1. upon failure, e.g. pre-conditions are not met

  double *vrna_positional_entropy(vrna_fold_compound_t *fc)

    Compute a vector of positional entropies.

        #include <ViennaRNA/probabilities/structures.h>

    This function computes the positional entropies from base pair probabilities as

    \[S(i) = - \sum_j p_{ij} \log(p_{ij}) - q_i \log(q_i) \]

    with unpaired probabilities \( q_i = 1 - \sum_j p_{ij} \).

    Low entropy regions have little structural flexibility and the reliability of the predicted structure is high. High entropy implies many structural alternatives. While these alternatives may be functionally important, they make structure prediction more difficult and thus less reliable.

    SWIG Wrapper Notes:

      This function is attached as method `positional_entropy()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.positional_entropy()` in the Python API.

    Parameters:

      - fc – A fold_compound with pre-computed base pair probabilities

    Pre:

      This function requires pre-computed base pair probabilities! Thus, vrna_pf() must be called beforehand.

    Returns:

      A 1-based vector of positional entropies \( S(i) \). (position 0 contains the sequence length)

  double vrna_pr_structure(vrna_fold_compound_t *fc, const char *structure)

    Compute the equilibrium probability of a particular secondary structure.

        #include <ViennaRNA/probabilities/structures.h>

    The probability \(p(s)\) of a particular secondary structure \(s\) can be computed as

    \[ p(s) = \frac{exp(-\beta E(s)}{Z} \]

    from the structures free energy \(E(s)\) and the partition function

    \[ Z = \sum_s exp(-\beta E(s)),\quad\mathrm{with}\quad\beta = \frac{1}{RT} \]

    where \(R\) is the gas constant and \(T\) the thermodynamic temperature.

    SWIG Wrapper Notes:

      This function is attached as method `pr_structure()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.pr_structure()` in the Python API.

    Parameters:

      - fc – The fold compound data structure with precomputed partition function

      - structure – The secondary structure to compute the probability for in dot-bracket notation

    Pre:

      The fold compound `fc` must have went through a call to vrna_pf() to fill the dynamic programming matrices with the corresponding partition function.

    Returns:

      The probability of the input structure (range \([0:1]\))

  double vrna_pr_energy(vrna_fold_compound_t *fc, double e)

        #include <ViennaRNA/probabilities/structures.h>

    SWIG Wrapper Notes:

      This function is attached as method `pr_energy()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.pr_energy()` in the Python API.

  Typedefs

  typedef void (*vrna_heat_capacity_f)(float temp, float heat_capacity, void *data)

    The callback for heat capacity predictions.

        #include <ViennaRNA/heat_capacity.h>

    Notes on Callback Functions:

      This function will be called for each evaluated temperature in the heat capacity prediction.

    See also

    vrna_heat_capacity_cb()

    Param temp:

      The current temperature this results corresponds to in °C

    Param heat_capacity:

      The heat capacity in Kcal/(Mol * K)

    Param data:

      Some arbitrary data pointer passed through by the function executing the callback

  typedef void vrna_heat_capacity_callback(float temp, float heat_capacity, void *data)

        #include <ViennaRNA/heat_capacity.h>

  typedef struct vrna_heat_capacity_s vrna_heat_capacity_t

    A single result from heat capacity computations.

        #include <ViennaRNA/heat_capacity.h>

    This is a convenience typedef for vrna_heat_capacity_s, i.e. results as obtained from vrna_heat_capacity()

  struct vrna_heat_capacity_s
    #include <ViennaRNA/heat_capacity.h>

    A single result from heat capacity computations.

    See also

    vrna_heat_capacity()

    Public Members

    float temperature

      The temperature in °C.

          #include <ViennaRNA/heat_capacity.h>

    float heat_capacity

      The specific heat at this temperature in Kcal/(Mol * K).

          #include <ViennaRNA/heat_capacity.h>