Predicting various Thermodynamic Properties
Compute various thermodynamic properties using the partition function.
Many thermodynamic properties can be derived from the partition function
In particular, for nucleic acids in equilibrium the probabilty \(p(F)\) of a particular structural feature \(F\) follows Boltzmanns law, i.e.:
The actual probabilities can then be obtained from the ratio of those structures containing \(F\) and all structures, i.e.
Consequently, a particular secondary structure \(s\) has equilibrium probability
which can be easily computed once \(Z\) and \(E(s)\) are known.
Efficient dynamic programming algorithms exist to compute the equilibrium probabilities
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
Base pair probabilities and derived computations

int vrna_pairing_probs(vrna_fold_compound_t *fc, char *structure)
 #include <ViennaRNA/equilibrium_probs.h>

double vrna_mean_bp_distance_pr(int length, FLT_OR_DBL *pr)
 #include <ViennaRNA/equilibrium_probs.h>
Get the mean base pair distance in the thermodynamic ensemble from a probability matrix.
\[ <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}(1p_{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)
 #include <ViennaRNA/equilibrium_probs.h>
Get the mean base pair distance in the thermodynamic ensemble.
\[ <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}(1p_{ij}) \] SWIG Wrapper Notes:
This function is attached as method
mean_bp_distance()
to objects of typefold_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)
 #include <ViennaRNA/equilibrium_probs.h>
Compute the Ensemble Defect for a given target structure provided as a vrna_ptable.
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 typefold_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 precomputed 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 usingfc
before execution of this function! Returns:
The ensemble defect with respect to the target structure, or 1. upon failure, e.g. preconditions are not met

double vrna_ensemble_defect(vrna_fold_compound_t *fc, const char *structure)
 #include <ViennaRNA/equilibrium_probs.h>
Compute the Ensemble Defect for a given target structure.
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 typefold_compound
. Note that the SWIG wrapper takes a structure in dotbracket 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 argumentoptions
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 precomputed base pair probabilities
structure – A target structure in dotbracket 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 usingfc
before execution of this function! Returns:
The ensemble defect with respect to the target structure, or 1. upon failure, e.g. preconditions are not met

double *vrna_positional_entropy(vrna_fold_compound_t *fc)
 #include <ViennaRNA/equilibrium_probs.h>
Compute a vector of positional entropies.
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 typefold_compound
. See, e.g.RNA.fold_compound.positional_entropy()
in the Python API.
 Parameters:
fc – A fold_compound with precomputed base pair probabilities
 Pre:
This function requires precomputed base pair probabilities! Thus, vrna_pf() must be called beforehand.
 Returns:
A 1based vector of positional entropies \( S(i) \). (position 0 contains the sequence length)

vrna_ep_t *vrna_stack_prob(vrna_fold_compound_t *fc, double cutoff)
 #include <ViennaRNA/equilibrium_probs.h>
Compute stacking probabilities.
For each possible base pair \((i,j)\), compute the probability of a stack \((i,j)\), \((i+1, j1)\).
 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)
 #include <ViennaRNA/equilibrium_probs.h>
Compute Boltzmann probabilities of dimerization without homodimers.
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_pr_structure(vrna_fold_compound_t *fc, const char *structure)
 #include <ViennaRNA/equilibrium_probs.h>
Compute the equilibrium probability of a particular secondary structure.
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 typefold_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 dotbracket 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/equilibrium_probs.h>
 SWIG Wrapper Notes:
This function is attached as method
pr_energy()
to objects of typefold_compound
. See, e.g.RNA.fold_compound.pr_energy()
in the Python 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)
 #include <ViennaRNA/heat_capacity.h>
Compute the specific heat for an RNA.
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
toT_max
, as well as the increment step sizeT_increment
. The latter also determines how many times the partition function is computed. Finally, the parametermpoints
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 typefold_compound
. If the optional function argumentsT_min
,T_max
,T_increment
, andmpoints
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.
 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 1C)
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)
 #include <ViennaRNA/heat_capacity.h>
Compute the specific heat for an RNA (callback variant)
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
toT_max
, as well as the increment step sizeT_increment
. The latter also determines how many times the partition function is computed. Finally, the parametermpoints
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 typefold_compound
. See, e.g.RNA.fold_compound.heat_capacity_cb()
in the Python API.
See also
 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 1C)
mpoints – The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100)
cb – The userdefined 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 nonzero 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)
 #include <ViennaRNA/heat_capacity.h>
Compute the specific heat for an RNA (simplified variant)
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
toT_max
, as well as the increment step sizeT_increment
. The latter also determines how many times the partition function is computed. Finally, the parametermpoints
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 argumentsT_min
,T_max
,T_increment
, andmpoints
are omitted, they default to 0.0, 100.0, 1.0 and 2, respectively. See, e.g.RNA.head_capacity()
in the Python API.
 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 1C)
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
Typedefs

typedef void (*vrna_heat_capacity_f)(float temp, float heat_capacity, void *data)
 #include <ViennaRNA/heat_capacity.h>
The callback for heat capacity predictions.
 Notes on Callback Functions:
This function will be called for each evaluated temperature in the heat capacity prediction.
See also
 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
 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
 #include <ViennaRNA/heat_capacity.h>
A single result from heat capacity computations.
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

int vrna_pairing_probs(vrna_fold_compound_t *fc, char *structure)