Energy Evaluation for Individual Loops

To assess the free energy contribution of a particular loop \(L\) within a secondary structure, two variants are provided

The bare free energy \(E_L\) (usually in units of deka-calories, i.e. multiples of \(10 \text{cal} \cdot \text{mol}^{-1}\), and
The Boltzmann weight \(q = exp(-\beta E_L)\) of the free energy \(E_L\) (with \(\beta = \frac{1}{RT}\), gas constant \(R\) and temperature \(T\))

The latter is usually required for partition function computations.

General 

Functions to evaluate the free energy of particular types of loops.

Functions

int vrna_eval_loop_pt(vrna_fold_compound_t *fc, int i, const short *pt)

#include <ViennaRNA/eval/structures.h>

Calculate energy of a loop.

SWIG Wrapper Notes:: This function is attached as method eval_loop_pt() to objects of type fold_compound. See, e.g. RNA.fold_compound.eval_loop_pt() in the Python API .

Parameters:

fc – A vrna_fold_compound_t containing the energy parameters and model details
i – position of covering base pair
pt – the pair table of the secondary structure

Returns:

free energy of the loop in 10cal/mol

int vrna_eval_loop_pt_v(vrna_fold_compound_t *fc, int i, const short *pt, int verbosity_level)

#include <ViennaRNA/eval/structures.h>

Calculate energy of a loop.

Parameters:

fc – A vrna_fold_compound_t containing the energy parameters and model details
i – position of covering base pair
pt – the pair table of the secondary structure
verbosity_level – The level of verbosity of this function

Returns:

free energy of the loop in 10cal/mol

Exterior Loops 

Functions to evaluate the free energy contributions for exterior (external) loops.

Boltzmann weight (partition function) interface

typedef struct vrna_mx_pf_aux_el_s *vrna_mx_pf_aux_el_t

#include <ViennaRNA/partfunc/exterior.h>

Auxiliary helper arrays for fast exterior loop computations.

See also

vrna_exp_E_ext_fast_init(), vrna_exp_E_ext_fast_rotate(), vrna_exp_E_ext_fast_free(), vrna_exp_E_ext_fast()

vrna_mx_pf_aux_el_t vrna_exp_E_ext_fast_init(vrna_fold_compound_t *fc): #include <ViennaRNA/partfunc/exterior.h>

void vrna_exp_E_ext_fast_rotate(vrna_mx_pf_aux_el_t aux_mx): #include <ViennaRNA/partfunc/exterior.h>

void vrna_exp_E_ext_fast_free(vrna_mx_pf_aux_el_t aux_mx): #include <ViennaRNA/partfunc/exterior.h>

FLT_OR_DBL vrna_exp_E_ext_fast(vrna_fold_compound_t *fc, int i, int j, vrna_mx_pf_aux_el_t aux_mx): #include <ViennaRNA/partfunc/exterior.h>

void vrna_exp_E_ext_fast_update(vrna_fold_compound_t *fc, int j, vrna_mx_pf_aux_el_t aux_mx): #include <ViennaRNA/partfunc/exterior.h>

Basic free energy interface

int vrna_E_exterior_stem(unsigned int type, int n5d, int n3d, vrna_param_t *p)

#include <ViennaRNA/eval/exterior.h>

Evaluate a stem branching off the exterior loop.

Given a base pair \((i,j)\) encoded by type, compute the energy contribution including dangling-end/terminal-mismatch contributions. Instead of returning the energy contribution per-se, this function returns the corresponding Boltzmann factor. If either of the adjacent nucleotides \((i - 1)\) and \((j+1)\) must not contribute stacking energy, the corresponding encoding must be \(-1\).

See also

vrna_exp_E_exterior_stem()

Note

By default, terminal mismatch energies are applied that correspond to the neighboring nucleotides provided by their encodings n5d and n3d. Whenever the encodings are negative, the implementation switches to usage of dangling end energies (for the non-negative base). If both encodings are negative, no terminal mismatch contributions are added.

Parameters:

type – The base pair encoding
n5d – The encoded nucleotide directly adjacent at the 5’ side of the base pair (may be -1)
n3d – The encoded nucleotide directly adjacent at the 3’ side of the base pair (may be -1)
p – The pre-computed energy parameters

Returns:

The energy contribution of the introduced exterior-loop stem

int vrna_E_exterior_loop(unsigned int n, vrna_md_t *md): #include <ViennaRNA/eval/exterior.h>

int vrna_eval_exterior_stem(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, unsigned int options)

#include <ViennaRNA/eval/exterior.h>

Evaluate the free energy of a base pair in the exterior loop.

Evalue the free energy of a base pair connecting two nucleotides in the exterior loop and take hard constraints into account.

Typically, this is simply dangling end contributions of the adjacent nucleotides, potentially a terminal A-U mismatch penalty, and maybe some generic soft constraint contribution for that decomposition.

See also

vrna_E_exterior_stem(), #VRNA_EVAL_LOOP_NO_HC, #VRNA_EVAL_LOOP_NO_SC, #VRNA_EVAL_LOOP_NO_CONSTRAINTS

Note

For dangles == 1 || 3 this function also evaluates the three additional pairs (i + 1, j), (i, j - 1), and (i + 1, j - 1) and returns the minimum for all four possibilities in total.

Note

By default, all user-supplied hard- and soft constraints will be taken into account! Use the #VRNA_EVAL_LOOP_NO_HC and #VRNA_EVAL_LOOP_NO_SC bit flags as input for options to change the default behavior if necessary.

Parameters:

fc – Fold compound to work on (defines the model and parameters)
i – 5’ position of the base pair
j – 3’ position of the base pair
options – A bit-field that specifies which aspects (not) to consider during evaluation

Returns:

Free energy for the terminal base pair of a stem branching off the exterior loop in deka-kal/mol or INF if the pair is forbidden

Boltzmann weight (partition function) interface

FLT_OR_DBL vrna_exp_E_exterior_stem(unsigned int type, int n5d, int n3d, vrna_exp_param_t *p)

#include <ViennaRNA/eval/exterior.h>

Evaluate a stem branching off the exterior loop (Boltzmann factor version)

Given a base pair \((i,j)\) encoded by type, compute the energy contribution including dangling-end/terminal-mismatch contributions. Instead of returning the energy contribution per-se, this function returns the corresponding Boltzmann factor.

See also

vrna_E_exterior()

Note

By default, terminal mismatch energies are applied that correspond to the neighboring nucleotides provided by their encodings n5d and n3d. Whenever the encodings are negative, the implementation switches to usage of dangling end energies (for the non-negative base). If both encodings are negative, no terminal mismatch contributions are added.

Parameters:

type – The base pair encoding
n5d – The encoded nucleotide directly adjacent at the 5’ side of the base pair (may be -1)
n3d – The encoded nucleotide directly adjacent at the 3’ side of the base pair (may be -1)
p – The pre-computed energy parameters (Boltzmann factor version)

Returns:

The Boltzmann weighted energy contribution of the introduced exterior-loop stem

FLT_OR_DBL vrna_exp_E_exterior_loop(unsigned int n, vrna_md_t *md): #include <ViennaRNA/eval/exterior.h>

Minimum Free Energy API

int vrna_mfe_exterior_f5(vrna_fold_compound_t *fc): #include <ViennaRNA/mfe/exterior.h>

int vrna_mfe_exterior_f3(vrna_fold_compound_t *fc, unsigned int i): #include <ViennaRNA/mfe/exterior.h>

Functions

int vrna_E_ext_loop_5(vrna_fold_compound_t *fc): #include <ViennaRNA/mfe/exterior.h>

int vrna_E_ext_loop_3(vrna_fold_compound_t *fc): #include <ViennaRNA/mfe/exterior.h>

Hairpin Loops 

Functions to evaluate the free energy contributions for hairpin loops.

Basic free energy interface

int vrna_E_hairpin(unsigned int size, unsigned int type, int si1, int sj1, const char *sequence, vrna_param_t *P)

#include <ViennaRNA/eval/hairpin.h>

Retrieve the energy of a hairpin-loop.

To evaluate the free energy of a hairpin-loop, several parameters have to be known. A general hairpin-loop has this structure: where X-Y marks the closing pair [e.g. a (G,C) pair]. The length of this loop is 6 as there are six unpaired nucleotides (a1-a6) enclosed by (X,Y). The 5’ mismatching nucleotide is a1 while the 3’ mismatch is a6. The nucleotide sequence of this loop is “a1.a2.a3.a4.a5.a6”

See also

vrna_param_t, vrna_eval_hp_loop()

Note

Whenever one of the mismatch base encodings si1 or sj1 is negative, terminal mismatch energies are not applied!

Note

The parameter sequence is a 0-terminated string of size size + 2 that contain the nucleic acid sequence of the loop in upper-case letters. This parameter is only required for loops of size below 7, since it is used for look-up of unusually stable tri-, tetra- and hexa-loops, such as GNRA tetra loops. Those may have additional sequence-dependent tabulated free energies available.

Warning

This function only evaluates the free energy of a hairpin loop according to the current Turner energy parameter set! No additional hard- or soft constraints are applied. See vrna_eval_hp_loop() for a function that also takes into account any user-supplied constraints!

Parameters:

size – The size of the loop (number of unpaired nucleotides)
type – The pair type of the base pair closing the hairpin
si1 – The 5’-mismatching nucleotide
sj1 – The 3’-mismatching nucleotide
sequence – The sequence of the loop (May be NULL, otherwise mst be at least \(size + 2\) long)
P – The datastructure containing scaled energy parameters

Returns:

The Free energy of the Hairpin-loop in dcal/mol

int vrna_eval_hairpin(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, unsigned int options)

#include <ViennaRNA/eval/hairpin.h>

Evaluate free energy of a hairpin loop.

This function evaluates the free energy of a hairpin loop closed by a base pair (i,j). By default (options = #VRNA_EVAL_DEFAULT), @emph all user-supplied constraints will be taken into consideration. This means that any hard constraints that prohibit the formation of this loop will result in an energy contribution of INF. On the other hand, if, given the set of constraints, the loop is allowed then its free energy is evaluated according to the Nearest Neighbor energy parameter set. On top of that, any user-supplied soft-constraints will be added, if applicable.

The options argument allows for (de-)activating certain aspects of the evaluation, e.g. hard constraints, soft constraints, etc.

See also

vrna_E_hairpin(), vrna_exp_eval_hairpin(), #VRNA_EVAL_LOOP_NO_HC, #VRNA_EVAL_LOOP_NO_SC, #VRNA_EVAL_LOOP_NO_CONSTRAINTS

Note

If sequence position i is larger than j, the function assumes a hairpin loop formed by a circular RNA, where the unpaired loop sequence spans the n,1-junction.

Note

By default, all user-supplied hard- and soft constraints will be taken into account! Use the #VRNA_EVAL_LOOP_NO_HC and #VRNA_EVAL_LOOP_NO_SC bit flags as input for options to change the default behavior if necessary.

Note

This function is polymorphic! The provided vrna_fold_compound_t may be of type VRNA_FC_TYPE_SINGLE or VRNA_FC_TYPE_COMPARATIVE

Parameters:

fc – The vrna_fold_compound_t for the particular energy evaluation
i – 5’-position of the base pair
j – 3’-position of the base pair
options – A bit-field that specifies which aspects (not) to consider during evaluation

Returns:

Free energy of the hairpin loop closed by \( (i,j) \) in deka-kal/mol or INF if the loop is forbidden

Boltzmann weight (partition function) interface

FLT_OR_DBL vrna_exp_E_hairpin(unsigned int size, unsigned int type, int si1, int sj1, const char *sequence, vrna_exp_param_t *P)

#include <ViennaRNA/eval/hairpin.h>

Compute Boltzmann weight \(e^{-\Delta G/kT} \) of a hairpin loop.

This is the partition function variant of vrna_E_hp() that returns the Boltzmann weight \(e^{-\Delta E/kT} \) instead of the energy \( E \).

See also

vrna_exp_eval_hp_loop(), vrna_exp_param_t, vrna_E_hp()

Note

Whenever one of the mismatch base encodings si1 or sj1 is negative, terminal mismatch energies are not applied!

Note

Do not forget to scale this Bolztmann factor properly, e.g. by multiplying with scale[u+2]

Parameters:

size – The size of the loop (number of unpaired nucleotides)
type – The pair type of the base pair closing the hairpin
si1 – The 5’-mismatching nucleotide
sj1 – The 3’-mismatching nucleotide
sequence – The sequence of the loop (May be NULL, otherwise mst be at least \(size + 2\) long)
P – The datastructure containing scaled Boltzmann weights of the energy parameters

Returns:

The Boltzmann weight of the Hairpin-loop

FLT_OR_DBL vrna_exp_eval_hairpin(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, unsigned int options)

#include <ViennaRNA/eval/hairpin.h>

High-Level function for hairpin loop energy evaluation (partition function variant)

This is the partition function variant of vrna_eval_hp_loop() that returns the Boltzmann weight \(e^{-\Delta E/kT} \) instead of the energy \( E \). On top of all constraints application, this function already scales the Boltzmann factor, i.e. it multiplies the result with scale[u + 2]

The options argument allows for (de-)activating certain aspects of the evaluation, e.g. hard constraints, soft constraints, etc.

See also

vrna_eval_hairpin(), vrna_exp_E_hairpin(), #VRNA_EVAL_LOOP_NO_HC, #VRNA_EVAL_LOOP_NO_SC, #VRNA_EVAL_LOOP_NO_CONSTRAINTS

Note

If sequence position i is larger than j, the function assumes a hairpin loop formed by a circular RNA, where the unpaired loop sequence spans the n,1-junction.

Note

By default, all user-supplied hard- and soft constraints will be taken into account! Use the #VRNA_EVAL_LOOP_NO_HC and #VRNA_EVAL_LOOP_NO_SC bit flags to change the default behavior if necessary.

Note

This function is polymorphic! The provided vrna_fold_compound_t may be of type VRNA_FC_TYPE_SINGLE or VRNA_FC_TYPE_COMPARATIVE

Parameters:

fc – The vrna_fold_compound_t for the particular energy evaluation
i – 5’-position of the base pair
j – 3’-position of the base pair
options – A bit-field that specifies which aspects (not) to consider during evaluation

Returns:

Boltzmann factor of the free energy of the hairpin loop closed by \( (i,j) \) or 0. if the loop is forbidden

Internal Loops 

Functions to evaluate the free energy contributions for internal loops.

Basic free energy interface

int vrna_E_internal(unsigned int n1, unsigned int n2, unsigned int type, unsigned int type_2, int si1, int sj1, int sp1, int sq1, vrna_param_t *P)

#include <ViennaRNA/eval/internal.h>

Compute the Energy of an internal loop.

This function computes the free energy \( E \) of an internal-loop with the following structure: This general structure depicts an internal-loop that is closed by the base pair (X,Y). The enclosed base pair is (V,U) which leaves the unpaired bases a_1-a_n and b_1-b_n that constitute the loop. In this example, the length of the internal-loop is \((n+m)\)

where n or m may be 0 resulting in a bulge-loop or base pair stack. The mismatching nucleotides for the closing pair (X,Y) are:

5’-mismatch: a_1

3’-mismatch: b_m

and for the enclosed base pair (V,U):

5’-mismatch: b_1

3’-mismatch: a_n

See also

vrna_exp_E_internal()

Note

Base pairs are always denoted in 5’->3’ direction. Thus the enclosed base pair must be ‘turned arround’ when evaluating the free energy of the internal-loop

This function is threadsafe

Parameters:

n1 – The size of the ‘left’-loop (number of unpaired nucleotides)
n2 – The size of the ‘right’-loop (number of unpaired nucleotides)
type – The pair type of the base pair closing the internal loop
type_2 – The pair type of the enclosed base pair
si1 – The 5’-mismatching nucleotide of the closing pair
sj1 – The 3’-mismatching nucleotide of the closing pair
sp1 – The 3’-mismatching nucleotide of the enclosed pair
sq1 – The 5’-mismatching nucleotide of the enclosed pair
P – The datastructure containing scaled energy parameters

Returns:

The Free energy of the internal loop in dcal/mol

int vrna_eval_internal(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, unsigned int k, unsigned int l, unsigned int options): #include <ViennaRNA/eval/internal.h>
Evaluate the free energy contribution of an internal loop with delimiting base pairs \((i,j)\) and \((k,l)\).

Note

This function is polymorphic, i.e. it accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE as well as VRNA_FC_TYPE_COMPARATIVE

int vrna_eval_stack(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, unsigned int options): #include <ViennaRNA/eval/internal.h>

Boltzmann weight (partition function) interface

FLT_OR_DBL vrna_exp_E_internal(unsigned int n1, unsigned int n2, unsigned int type, unsigned int type_2, int si1, int sj1, int sp1, int sq1, vrna_exp_param_t *P): #include <ViennaRNA/eval/internal.h>

FLT_OR_DBL vrna_exp_eval_internal(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, unsigned int k, unsigned int l, unsigned int options): #include <ViennaRNA/eval/internal.h>

Minimum Free Energy API

int vrna_mfe_internal(vrna_fold_compound_t *fc, unsigned int i, unsigned int j): #include <ViennaRNA/mfe/internal.h>

int vrna_mfe_internal_ext(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, unsigned int *ip, unsigned int *iq): #include <ViennaRNA/mfe/internal.h>

Boltzmann weight (partition function) interface

FLT_OR_DBL vrna_exp_E_int_loop(vrna_fold_compound_t *fc, int i, int j): #include <ViennaRNA/partfunc/internal.h>

Functions

int vrna_E_int_loop(vrna_fold_compound_t *fc, int i, int j): #include <ViennaRNA/mfe/internal.h>

int vrna_E_ext_int_loop(vrna_fold_compound_t *fc, int i, int j, int *ip, int *iq): #include <ViennaRNA/mfe/internal.h>

Multibranch Loops 

Functions to evaluate the free energy contributions for mutlibranch loops.

Minimum Free Energy API

typedef struct vrna_mx_mfe_aux_ml_s *vrna_mx_mfe_aux_ml_t: #include <ViennaRNA/mfe/multibranch.h>

vrna_mx_mfe_aux_ml_t vrna_mfe_multibranch_fast_init(unsigned int length): #include <ViennaRNA/mfe/multibranch.h>

void vrna_mfe_multibranch_fast_rotate(vrna_mx_mfe_aux_ml_t aux): #include <ViennaRNA/mfe/multibranch.h>

void vrna_mfe_multibranch_fast_free(vrna_mx_mfe_aux_ml_t aux): #include <ViennaRNA/mfe/multibranch.h>

int vrna_mfe_multibranch_loop_fast(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, vrna_mx_mfe_aux_ml_t helpers): #include <ViennaRNA/mfe/multibranch.h>

int vrna_mfe_multibranch_stems_fast(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, struct vrna_mx_mfe_aux_ml_s *helpers): #include <ViennaRNA/mfe/multibranch.h>

int vrna_mfe_multibranch_m2_fast(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, struct vrna_mx_mfe_aux_ml_s *helpers): #include <ViennaRNA/mfe/multibranch.h>

int vrna_mfe_multibranch_loop_stack(vrna_fold_compound_t *fc, unsigned int i, unsigned int j)

#include <ViennaRNA/mfe/multibranch.h>

Evaluate energy of multi branch loop helices stacking onto closing pair (i,j)

Computes total free energy for coaxial stacking of (i.j) with (i+1.k) or (k+1.j-1)

int vrna_mfe_multibranch_m1(vrna_fold_compound_t *fc, unsigned int i, unsigned int j): #include <ViennaRNA/mfe/multibranch.h>

Boltzmann weight (partition function) interface

typedef struct vrna_mx_pf_aux_ml_s *vrna_mx_pf_aux_ml_t

#include <ViennaRNA/partfunc/multibranch.h>

Auxiliary helper arrays for fast exterior loop computations.

See also

vrna_exp_E_ml_fast_init(), vrna_exp_E_ml_fast_rotate(), vrna_exp_E_ml_fast_free(), vrna_exp_E_ml_fast()

FLT_OR_DBL vrna_exp_E_mb_loop_fast(vrna_fold_compound_t *fc, int i, int j, vrna_mx_pf_aux_ml_t aux_mx): #include <ViennaRNA/partfunc/multibranch.h>

vrna_mx_pf_aux_ml_t vrna_exp_E_ml_fast_init(vrna_fold_compound_t *fc): #include <ViennaRNA/partfunc/multibranch.h>

void vrna_exp_E_ml_fast_rotate(vrna_mx_pf_aux_ml_t aux_mx): #include <ViennaRNA/partfunc/multibranch.h>

void vrna_exp_E_ml_fast_free(vrna_mx_pf_aux_ml_t aux_mx): #include <ViennaRNA/partfunc/multibranch.h>

const FLT_OR_DBL *vrna_exp_E_ml_fast_qqm(vrna_mx_pf_aux_ml_t aux_mx): #include <ViennaRNA/partfunc/multibranch.h>

const FLT_OR_DBL *vrna_exp_E_ml_fast_qqm1(vrna_mx_pf_aux_ml_t aux_mx): #include <ViennaRNA/partfunc/multibranch.h>

FLT_OR_DBL vrna_exp_E_ml_fast(vrna_fold_compound_t *fc, int i, int j, vrna_mx_pf_aux_ml_t aux_mx): #include <ViennaRNA/partfunc/multibranch.h>

FLT_OR_DBL vrna_exp_E_m2_fast(vrna_fold_compound_t *fc, int i, int j, struct vrna_mx_pf_aux_ml_s *aux_mx): #include <ViennaRNA/partfunc/multibranch.h>

Basic free energy interface

int vrna_E_multibranch_stem(unsigned int type, int si1, int sj1, vrna_param_t *P)

#include <ViennaRNA/eval/multibranch.h>

Evaluate the free energy contribution of a stem branching off a multibranch loop.

This function yields the free energy contribution for the terminal base pairs of a stem branching off a multibranch loop. In essence, this consists of (i) a terminal mismatch or dangling end contribution, (ii) the score for a stem according to the affine multibranch loop model, and (iii) a terminal AU/GU penalty, if applicable.

Note

By default, terminal mismatch energies are applied that correspond to the neighboring nucleotides provided by their encodings n5d and n3d. Whenever the encodings are negative, the implementation switches to usage of dangling end energies (for the non-negative base). If both encodings are negative, no terminal mismatch contributions are added.

Parameters:

type – The base pair encoding
si1 – The encoded nucleotide directly adjacent at the 5’ side of the base pair (may be -1)
sj1 – The encoded nucleotide directly adjacent at the 3’ side of the base pair (may be -1)
p – The pre-computed energy parameters

Returns:

The energy contribution of the introduced mutlibranch loop stem

Boltzmann weight (partition function) interface

FLT_OR_DBL vrna_exp_E_multibranch_stem(unsigned int type, int si1, int sj1, vrna_exp_param_t *P)

#include <ViennaRNA/eval/multibranch.h>

Evaluate the free energy contribution of a stem branching off a multibranch loop (Boltzmann factor version)

This function yields the free energy contribution as Boltzmann factor \( exp(-E/kT) \) for the terminal base pairs of a stem branching off a multibranch loop. In essence, this consists of (i) a terminal mismatch or dangling end contribution, (ii) the score for a stem according to the affine multibranch loop model, and (iii) a terminal AU/GU penalty, if applicable.

Note

By default, terminal mismatch energies are applied that correspond to the neighboring nucleotides provided by their encodings n5d and n3d. Whenever the encodings are negative, the implementation switches to usage of dangling end energies (for the non-negative base). If both encodings are negative, no terminal mismatch contributions are added.

Parameters:

type – The base pair encoding
si1 – The encoded nucleotide directly adjacent at the 5’ side of the base pair (may be -1)
sj1 – The encoded nucleotide directly adjacent at the 3’ side of the base pair (may be -1)
p – The pre-computed energy parameters (Boltzmann factor version)

Returns:

The Boltzmann factor of the energy contribution for the introduced mutlibranch loop stem

Energy Evaluation for Individual Loops

General

Exterior Loops

Hairpin Loops

Internal Loops

Multibranch Loops

General 

Exterior Loops 

Hairpin Loops 

Internal Loops 

Multibranch Loops 