RNAlib-2.5.1

Compute various thermodynamic properties using the partition function. More...

Detailed Description

Compute various thermodynamic properties using the partition function.

Many thermodynamic properties can be derived from the partition function

\[ Q = \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}{Q} \sum_{s \mid F \in s} e^{\frac{-E(s)}{kT}}. \]

Consequently, a particular secondary structure $ s $ has equilibrium probability

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

which can be easily computed once $ Q $ and $ E(s) $ are known.

On the other hand, efficient dynamic programming algorithms exist to compute the equilibrium probabilities

\[ p_{ij} = \frac{1}{Q} \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.

+ Collaboration diagram for Predicting various thermodynamic properties:

Files

file  equilibrium_probs.h
 Equilibrium Probability implementations.
 
file  heat_capacity.h
 Compute heat capacity for an RNA.
 

Data Structures

struct  vrna_heat_capacity_s
 A single result from heat capacity computations. More...
 

Typedefs

typedef void() vrna_heat_capacity_callback(float temp, float heat_capacity, void *data)
 The callback for heat capacity predictions. More...
 
typedef struct vrna_heat_capacity_s vrna_heat_capacity_t
 A single result from heat capacity computations. More...
 

Base pair probabilities and derived computations

int vrna_pairing_probs (vrna_fold_compound_t *vc, char *structure)
 
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. More...
 
double vrna_mean_bp_distance (vrna_fold_compound_t *vc)
 Get the mean base pair distance in the thermodynamic ensemble. More...
 
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. More...
 
double vrna_ensemble_defect (vrna_fold_compound_t *fc, const char *structure)
 Compute the Ensemble Defect for a given target structure. More...
 
double * vrna_positional_entropy (vrna_fold_compound_t *fc)
 Compute a vector of positional entropies. More...
 
vrna_ep_tvrna_stack_prob (vrna_fold_compound_t *vc, double cutoff)
 Compute stacking probabilities. More...
 

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. More...
 

Structure probability computations

double vrna_pr_structure (vrna_fold_compound_t *fc, const char *structure)
 Compute the equilibrium probability of a particular secondary structure. More...
 
double vrna_pr_energy (vrna_fold_compound_t *vc, double e)
 

Basic heat capacity function interface

vrna_heat_capacity_tvrna_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. More...
 
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_callback *cb, void *data)
 Compute the specific heat for an RNA (callback variant) More...
 

Simplified heat capacity computation

vrna_heat_capacity_tvrna_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) More...
 

Data Structure Documentation

◆ vrna_heat_capacity_s

struct vrna_heat_capacity_s

A single result from heat capacity computations.

See also
vrna_heat_capacity()

Data Fields

float temperature
 The temperature in °C.
 
float heat_capacity
 The specific heat at this temperature in Kcal/(Mol * K)
 

Typedef Documentation

◆ vrna_heat_capacity_callback

typedef void() vrna_heat_capacity_callback(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
vrna_heat_capacity_cb()
Parameters
tempThe current temperature this results corresponds to in °C
heat_capacityThe heat capacity in Kcal/(Mol * K)
dataSome arbitrary data pointer passed through by the function executing the callback

◆ 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()

Function Documentation

◆ vrna_mean_bp_distance_pr()

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}(1-p_{ij}) \]

Parameters
lengthThe length of the sequence
prThe matrix containing the base pair probabilities
Returns
The mean pair distance of the structure ensemble

◆ vrna_mean_bp_distance()

double vrna_mean_bp_distance ( vrna_fold_compound_t vc)

#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}(1-p_{ij}) \]

Parameters
vcThe fold compound data structure
Returns
The mean pair distance of the structure ensemble
SWIG Wrapper Notes:
This function is attached as method mean_bp_distance() to objects of type fold_compound

◆ vrna_ensemble_defect_pt()

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.

Precondition
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!
See also
vrna_pf(), vrna_pairing_probs(), vrna_ensemble_defect()
Parameters
fcA fold_compound with pre-computed base pair probabilities
ptA pair table representing a target structure
Returns
The ensemble defect with respect to the target structure, or -1. upon failure, e.g. pre-conditions are not met
SWIG Wrapper Notes:
This function is attached as overloaded method ensemble_defect() to objects of type fold_compound.

◆ vrna_ensemble_defect()

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.

Precondition
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!
See also
vrna_pf(), vrna_pairing_probs(), vrna_ensemble_defect_pt()
Parameters
fcA fold_compound with pre-computed base pair probabilities
structureA target structure in dot-bracket notation
Returns
The ensemble defect with respect to the target structure, or -1. upon failure, e.g. pre-conditions are not met
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).

◆ vrna_positional_entropy()

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.

Precondition
This function requires pre-computed base pair probabilities! Thus, vrna_pf() must be called beforehand.
Parameters
fcA fold_compound with pre-computed base pair probabilities
Returns
A 1-based vector of positional entropies $ S(i) $. (position 0 contains the sequence length)
SWIG Wrapper Notes:
This function is attached as method positional_entropy() to objects of type fold_compound

◆ vrna_stack_prob()

vrna_ep_t * vrna_stack_prob ( vrna_fold_compound_t vc,
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, j-1)$.

Parameters
vcThe fold compound data structure with precomputed base pair probabilities
cutoffA 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 $

◆ vrna_pf_dimer_probs()

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
FABfree energy of dimer AB
FAfree energy of monomer A
FBfree energy of monomer B
prABpair probabilities for dimer
prApair probabilities monomer
prBpair probabilities monomer
AlengthLength of molecule A
exp_paramsThe precomputed Boltzmann factors

◆ vrna_pr_structure()

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.

Precondition
The fold compound fc must have went through a call to vrna_pf() to fill the dynamic programming matrices with the corresponding partition function.
Parameters
fcThe fold compound data structure with precomputed partition function
structureThe secondary structure to compute the probability for in dot-bracket notation
Returns
The probability of the input structure (range $[0:1]$)
SWIG Wrapper Notes:
This function is attached as method pr_structure() to objects of type fold_compound

◆ vrna_pr_energy()

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 type fold_compound

◆ vrna_heat_capacity()

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 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.

See also
vrna_heat_capacity_cb(), vrna_heat_capacity_t, vrna_heat_capacity_s
Parameters
fcThe vrna_fold_compound_t with the RNA sequence to analyze
T_minLowest temperature in °C
T_maxHighest temperature in °C
T_incrementStepsize for temperature incrementation in °C (a reasonable choice might be 1°C)
mpointsThe 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
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.

◆ vrna_heat_capacity_cb()

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_callback 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 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.

See also
vrna_heat_capacity(), vrna_heat_capacity_callback
Parameters
fcThe vrna_fold_compound_t with the RNA sequence to analyze
T_minLowest temperature in °C
T_maxHighest temperature in °C
T_incrementStepsize for temperature incrementation in °C (a reasonable choice might be 1°C)
mpointsThe number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100)
cbThe user-defined callback function that receives the individual results
dataAn arbitrary data structure that will be passed to the callback in conjunction with the results
Returns
Returns 0 upon failure, and non-zero otherwise
SWIG Wrapper Notes:
This function is attached as method heat_capacity_cb() to objects of type fold_compound

◆ vrna_heat_capacity_simple()

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 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.

See also
vrna_heat_capacity(), vrna_heat_capacity_cb(), vrna_heat_capacity_t, vrna_heat_capacity_s
Parameters
sequenceThe RNA sequence input (must be uppercase)
T_minLowest temperature in °C
T_maxHighest temperature in °C
T_incrementStepsize for temperature incrementation in °C (a reasonable choice might be 1°C)
mpointsThe 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
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.