Processing and Evaluating Decomposed Loops

## Files

file | exterior_loops.h
| Energy evaluation of exterior loops for MFE and partition function calculations.
file | gquad.h
| Various functions related to G-quadruplex computations.
file | hairpin_loops.h
| Energy evaluation of hairpin loops for MFE and partition function calculations.
file | interior_loops.h
| Energy evaluation of interior loops for MFE and partition function calculations.
file | loop_energies.h
| Energy evaluation for MFE and partition function calculations.
file | multibranch_loops.h
| Energy evaluation of multibranch loops for MFE and partition function calculations.

## Functions

int | E_ExtLoop (int type, int si1, int sj1, vrna_param_t *P)
FLT_OR_DBL | exp_E_ExtLoop (int type, int si1, int sj1, vrna_exp_param_t *P)
int | E_Stem (int type, int si1, int sj1, int extLoop, vrna_param_t *P)
FLT_OR_DBL | exp_E_Stem (int type, int si1, int sj1, int extLoop, vrna_exp_param_t *P)
int * | get_gquad_matrix (short *S, vrna_param_t *P)
| Get a triangular matrix prefilled with minimum free energy contributions of G-quadruplexes. More...
int | parse_gquad (const char *struc, int *L, int l[3])
PRIVATE int | backtrack_GQuad_IntLoop (int c, int i, int j, int type, short *S, int *ggg, int *index, int *p, int *q, vrna_param_t *P)
PRIVATE int | backtrack_GQuad_IntLoop_L (int c, int i, int j, int type, short *S, int **ggg, int maxdist, int *p, int *q, vrna_param_t *P)
PRIVATE int | E_Hairpin (int size, int type, int si1, int sj1, const char *string, vrna_param_t *P)
| Compute the Energy of a hairpin-loop. More...
PRIVATE FLT_OR_DBL | exp_E_Hairpin (int u, int type, short si1, short sj1, const char *string, vrna_exp_param_t *P)
| Compute Boltzmann weight of a hairpin loop. More...
int | vrna_E_hp_loop (vrna_fold_compound_t *vc, int i, int j)
| Evaluate the free energy of a hairpin loop and consider possible hard constraints. More...
int | vrna_E_ext_hp_loop (vrna_fold_compound_t *vc, int i, int j)
| Evaluate the free energy of an exterior hairpin loop and consider possible hard constraints. More...
FLT_OR_DBL | vrna_exp_E_hp_loop (vrna_fold_compound_t *vc, int i, int j)
| High-Level function for hairpin loop energy evaluation (partition function variant) More...
int | vrna_BT_hp_loop (vrna_fold_compound_t *vc, int i, int j, int en, vrna_bp_stack_t *bp_stack, int *stack_count)
| Backtrack a hairpin loop closed by . More...
PRIVATE int | E_IntLoop (int n1, int n2, int type, int type_2, int si1, int sj1, int sp1, int sq1, vrna_param_t *P)
PRIVATE FLT_OR_DBL | exp_E_IntLoop (int u1, int u2, int type, int type2, short si1, short sj1, short sp1, short sq1, vrna_exp_param_t *P)
int | E_stack (int i, int j, vrna_fold_compound_t *vc)
| Evaluate energy of a base pair stack closed by (i,j)
int | vrna_BT_stack (vrna_fold_compound_t *vc, int *i, int *j, int *en, vrna_bp_stack_t *bp_stack, int *stack_count)
| Backtrack a stacked pair closed by .
int | vrna_BT_int_loop (vrna_fold_compound_t *vc, int *i, int *j, int en, vrna_bp_stack_t *bp_stack, int *stack_count)
| Backtrack an interior loop closed by .
int | E_mb_loop_stack (int i, int j, vrna_fold_compound_t *vc)
| Evaluate energy of a multi branch helices stacking onto closing pair (i,j) More...
int | vrna_BT_mb_loop (vrna_fold_compound_t *vc, int *i, int *j, int *k, int en, int *component1, int *component2)
| Backtrack the decomposition of a multi branch loop closed by . More...

## Detailed Description

## Function Documentation

int E_ExtLoop | ( | int | type,
|  | int | si1,
|  | int | sj1,
|  | vrna_param_t * | P
| ) |  |

`#include <ViennaRNA/exterior_loops.h>`

## Compute the Energy contribution of an Exterior loop stem

This definition is a wrapper for the E_Stem() funtion. It is substituted by an E_Stem() funtion call with argument extLoop=1, so the energy contribution returned reflects a stem introduced in an exterior-loop.
As for the parameters si1 and sj1 of the substituted E_Stem() function, you can inhibit to take 5'-, 3'-dangles or mismatch contributions to be taken into account by passing -1 to these parameters.

See also
  E_Stem()

Parameters

  type | The pair type of the stem-closing pair
  si1 | The 5'-mismatching nucleotide
  sj1 | The 3'-mismatching nucleotide
  P | The datastructure containing scaled energy parameters

Returns
  The energy contribution of the introduced exterior-loop stem

FLT_OR_DBL exp_E_ExtLoop | ( | int | type,
|  | int | si1,
|  | int | sj1,
|  | vrna_exp_param_t * | P
| ) |  |

`#include <ViennaRNA/exterior_loops.h>`

This is the partition function variant of E_ExtLoop()

See also
  E_ExtLoop()

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

int E_Stem | ( | int | type,
|  | int | si1,
|  | int | sj1,
|  | int | extLoop,
|  | vrna_param_t * | P
| ) |  |

`#include <ViennaRNA/exterior_loops.h>`

## Compute the energy contribution of a stem branching off a loop-region

This function computes the energy contribution of a stem that branches off a loop region. This can be the case in multiloops, when a stem branching off increases the degree of the loop but also immediately interior base pairs of an exterior loop contribute free energy. To switch the bahavior of the function according to the evaluation of a multiloop- or exterior-loop-stem, you pass the flag 'extLoop'. The returned energy contribution consists of a TerminalAU penalty if the pair type is greater than 2, dangling end contributions of mismatching nucleotides adjacent to the stem if only one of the si1, sj1 parameters is greater than 0 and mismatch energies if both mismatching nucleotides are positive values. Thus, to avoid incooperating dangling end or mismatch energies just pass a negative number, e.g. -1 to the mismatch argument.

This is an illustration of how the energy contribution is assembled:

          3'  5'
          |   |
          X - Y
    5'-si1     sj1-3'

Here, (X,Y) is the base pair that closes the stem that branches off a loop region. The nucleotides si1 and sj1 are the 5'- and 3'- mismatches, respectively. If the base pair type of (X,Y) is greater than 2 (i.e. an A-U or G-U pair, the TerminalAU penalty will be included in the energy contribution returned. If si1 and sj1 are both nonnegative numbers, mismatch energies will also be included. If one of sij or sj1 is a negtive value, only 5' or 3' dangling end contributions are taken into account. To prohibit any of these mismatch contributions to be incoorporated, just pass a negative number to both, si1 and sj1. In case the argument extLoop is 0, the returned energy contribution also includes the internal-loop-penalty of a multiloop stem with closing pair type.

See also
  E_MLstem()
  E_ExtLoop()

Note
  This function is threadsafe

Parameters

  type | The pair type of the first base pair un the stem
  si1 | The 5'-mismatching nucleotide
  sj1 | The 3'-mismatching nucleotide
  extLoop | A flag that indicates whether the contribution reflects the one of an exterior loop or not
  P | The datastructure containing scaled energy parameters

Returns
  The Free energy of the branch off the loop in dcal/mol

FLT_OR_DBL exp_E_Stem | ( | int | type,
|  | int | si1,
|  | int | sj1,
|  | int | extLoop,
|  | vrna_exp_param_t * | P
| ) |  |

`#include <ViennaRNA/exterior_loops.h>`

## Compute the Boltzmann weighted energy contribution of a stem branching off a loop-region

This is the partition function variant of E_Stem()

See also
  E_Stem()

Note
  This function is threadsafe

Returns
  The Boltzmann weighted energy contribution of the branch off the loop

int* get_gquad_matrix | ( | short * | S,
|  | vrna_param_t * | P
| ) |  |

`#include <ViennaRNA/gquad.h>`

Get a triangular matrix prefilled with minimum free energy contributions of G-quadruplexes.

At each position ij in the matrix, the minimum free energy of any G-quadruplex delimited by i and j is stored. If no G-quadruplex formation is possible, the matrix element is set to INF. Access the elements in the matrix via matrix[indx[j]+i]. To get the integer array indx see get_jindx().

See also
  get_jindx(), encode_sequence()

Parameters

  S | The encoded sequence
  P | A pointer to the data structure containing the precomputed energy contributions

Returns
  A pointer to the G-quadruplex contribution matrix

int parse_gquad | ( | const char * | struc,
|  | int * | L,
|  | int | l[3]
| ) |  |

`#include <ViennaRNA/gquad.h>`

given a dot-bracket structure (possibly) containing gquads encoded by '+' signs, find first gquad, return end position or 0 if none found Upon return L and l[] contain the number of stacked layers, as well as the lengths of the linker regions. To parse a string with many gquads, call parse_gquad repeatedly e.g. end1 = parse_gquad(struc, &L, l); ... ; end2 = parse_gquad(struc+end1, &L, l); end2+=end1; ... ; end3 = parse_gquad(struc+end2, &L, l); end3+=end2; ... ;

PRIVATE int backtrack_GQuad_IntLoop | ( | int | c,
|  | int | i,
|  | int | j,
|  | int | type,
|  | short * | S,
|  | int * | ggg,
|  | int * | index,
|  | int * | p,
|  | int * | q,
|  | vrna_param_t * | P
| ) |  |

`#include <ViennaRNA/gquad.h>`

backtrack an interior loop like enclosed g-quadruplex with closing pair (i,j)

Parameters

  c | The total contribution the loop should resemble
  i | position i of enclosing pair
  j | position j of enclosing pair
  type | base pair type of enclosing pair (must be reverse type)
  S | integer encoded sequence
  ggg | triangular matrix containing g-quadruplex contributions
  index | the index for accessing the triangular matrix
  p | here the 5' position of the gquad is stored
  q | here the 3' position of the gquad is stored
  P | the datastructure containing the precalculated contibutions

Returns
  1 on success, 0 if no gquad found

PRIVATE int backtrack_GQuad_IntLoop_L | ( | int | c,
|  | int | i,
|  | int | j,
|  | int | type,
|  | short * | S,
|  | int ** | ggg,
|  | int | maxdist,
|  | int * | p,
|  | int * | q,
|  | vrna_param_t * | P
| ) |  |

`#include <ViennaRNA/gquad.h>`

backtrack an interior loop like enclosed g-quadruplex with closing pair (i,j) with underlying Lfold matrix

Parameters

  c | The total contribution the loop should resemble
  i | position i of enclosing pair
  j | position j of enclosing pair
  type | base pair type of enclosing pair (must be reverse type)
  S | integer encoded sequence
  ggg | triangular matrix containing g-quadruplex contributions
  p | here the 5' position of the gquad is stored
  q | here the 3' position of the gquad is stored
  P | the datastructure containing the precalculated contibutions

Returns
  1 on success, 0 if no gquad found

PRIVATE int E_Hairpin | ( | int | size,
|  | int | type,
|  | int | si1,
|  | int | sj1,
|  | const char * | string,
|  | vrna_param_t * | P
| ) |  |

`#include <ViennaRNA/hairpin_loops.h>`

Compute 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:

          a3 a4
        a2     a5
        a1     a6
          X - Y
          |   |
          5'  3'

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"

Note
  The parameter sequence should contain the sequence of the loop in capital letters of the nucleic acid alphabet if the loop size is below 7. This is useful for unusually stable tri-, tetra- and hexa-loops which are treated differently (based on experimental data) if they are tabulated.

See also
  scale_parameters()
  vrna_param_t

Warning
  Not (really) thread safe! A threadsafe implementation will replace this function in a future release!
  Energy evaluation may change due to updates in global variable "tetra_loop"

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
  string | The sequence of the loop
  P | The datastructure containing scaled energy parameters

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

PRIVATE FLT_OR_DBL exp_E_Hairpin | ( | int | u,
|  | int | type,
|  | short | si1,
|  | short | sj1,
|  | const char * | string,
|  | vrna_exp_param_t * | P
| ) |  |

`#include <ViennaRNA/hairpin_loops.h>`

Compute Boltzmann weight of a hairpin loop.

multiply by scale[u+2]

See also
  get_scaled_pf_parameters()
  vrna_exp_param_t
  E_Hairpin()

Warning
  Not (really) thread safe! A threadsafe implementation will replace this function in a future release!
  Energy evaluation may change due to updates in global variable "tetra_loop"

Parameters

  u | 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
  string | The sequence of the loop
  P | The datastructure containing scaled Boltzmann weights of the energy parameters

Returns
  The Boltzmann weight of the Hairpin-loop

int vrna_E_hp_loop | ( | vrna_fold_compound_t * | vc,
|  | int | i,
|  | int | j
| ) |  |

`#include <ViennaRNA/hairpin_loops.h>`

Evaluate the free energy of a hairpin loop and consider possible hard constraints.

Note
  This function is polymorphic! The provided vrna_fold_compound_t may be of type VRNA_VC_TYPE_SINGLE or VRNA_VC_TYPE_ALIGNMENT

int vrna_E_ext_hp_loop | ( | vrna_fold_compound_t * | vc,
|  | int | i,
|  | int | j
| ) |  |

`#include <ViennaRNA/hairpin_loops.h>`

Evaluate the free energy of an exterior hairpin loop and consider possible hard constraints.

Note
  This function is polymorphic! The provided vrna_fold_compound_t may be of type VRNA_VC_TYPE_SINGLE or VRNA_VC_TYPE_ALIGNMENT

FLT_OR_DBL vrna_exp_E_hp_loop | ( | vrna_fold_compound_t * | vc,
|  | int | i,
|  | int | j
| ) |  |

`#include <ViennaRNA/hairpin_loops.h>`

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

See also
  vrna_E_hp_loop() for it's free energy counterpart

Note
  This function is polymorphic! The provided vrna_fold_compound_t may be of type VRNA_VC_TYPE_SINGLE or VRNA_VC_TYPE_ALIGNMENT

int vrna_BT_hp_loop | ( | vrna_fold_compound_t * | vc,
|  | int | i,
|  | int | j,
|  | int | en,
|  | vrna_bp_stack_t * | bp_stack,
|  | int * | stack_count
| ) |  |

`#include <ViennaRNA/hairpin_loops.h>`

Backtrack a hairpin loop closed by .

Note
  This function is polymorphic! The provided vrna_fold_compound_t may be of type VRNA_VC_TYPE_SINGLE or VRNA_VC_TYPE_ALIGNMENT

int E_IntLoop | ( | int | n1,
|  | int | n2,
|  | int | type,
|  | int | type_2,
|  | int | si1,
|  | int | sj1,
|  | int | sp1,
|  | int | sq1,
|  | vrna_param_t * | P
| ) |  |

`#include <ViennaRNA/interior_loops.h>`

## Compute the Energy of an interior-loop

This function computes the free energy of an interior-loop with the following structure:

          3'  5'
          |   |
          U - V
      a_n       b_1
       .        .
       .        .
       .        .
      a_1       b_m
          X - Y
          |   |
          5'  3'

This general structure depicts an interior-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 interior-loop is 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

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 interior-loop

See also
  scale_parameters()
  vrna_param_t

Note
  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 interior 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 Interior-loop in dcal/mol

PUBLIC FLT_OR_DBL exp_E_IntLoop | ( | int | u1,
|  | int | u2,
|  | int | type,
|  | int | type2,
|  | short | si1,
|  | short | sj1,
|  | short | sp1,
|  | short | sq1,
|  | vrna_exp_param_t * | P
| ) |  |

`#include <ViennaRNA/interior_loops.h>`

## Compute Boltzmann weight of interior loop

multiply by scale[u1+u2+2] for scaling

See also
  get_scaled_pf_parameters()
  vrna_exp_param_t
  E_IntLoop()

Note
  This function is threadsafe

Parameters

  u1 | The size of the 'left'-loop (number of unpaired nucleotides)
  u2 | The size of the 'right'-loop (number of unpaired nucleotides)
  type | The pair type of the base pair closing the interior loop
  type2 | 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 Boltzmann weights of the energy parameters

Returns
  The Boltzmann weight of the Interior-loop

int E_mb_loop_stack | ( | int | i,
|  | int | j,
|  | vrna_fold_compound_t * | vc
| ) |  |

`#include <ViennaRNA/multibranch_loops.h>`

Evaluate energy of a multi branch 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_BT_mb_loop | ( | vrna_fold_compound_t * | vc,
|  | int * | i,
|  | int * | j,
|  | int * | k,
|  | int | en,
|  | int * | component1,
|  | int * | component2
| ) |  |

`#include <ViennaRNA/multibranch_loops.h>`

Backtrack the decomposition of a multi branch loop closed by .

Parameters

  vc | The vrna_fold_compound_t filled with all relevant data for backtracking
  i | 5' position of base pair closing the loop (will be set to 5' position of leftmost decomposed block upon successful backtracking)
  j | 3' position of base pair closing the loop (will be set to 3' position of rightmost decomposed block upon successful backtracking)
  k | Split position that delimits leftmost from rightmost block, [i,k] and [k+1, j], respectively. (Will be set upon successful backtracking)
  en | The energy contribution of the substructure enclosed by
  component1 | Type of leftmost block (1 = ML, 2 = C)
  component2 | Type of rightmost block (1 = ML, 2 = C)

Returns
  1, if backtracking succeeded, 0 otherwise.