Constraining the RNA Folding Grammar

This module provides general functions that allow for an easy control of constrained secondary structure prediction and evaluation. More...

Detailed Description

This module provides general functions that allow for an easy control of constrained secondary structure prediction and evaluation.

Secondary Structure constraints can be subdivided into two groups:

• Hard Constraints, and
• Soft Constraints.

While Hard-Constraints directly influence the production rules used in the folding recursions by allowing, disallowing, or enforcing certain decomposition steps, Soft-constraints on the other hand are used to change position specific contributions in the recursions by adding bonuses/penalties in form of pseudo free energies to certain loop configurations.

Secondary structure constraints are always applied at decomposition level, i.e. in each step of the recursive structure decomposition, for instance during MFE prediction. Below is a visualization of the decomposition scheme

For Hard Constraints the following option flags may be used to constrain the pairing behavior of single, or pairs of nucleotides:

• VRNA_CONSTRAINT_CONTEXT_EXT_LOOP - Hard constraints flag, base pair in the exterior loop.
• VRNA_CONSTRAINT_CONTEXT_HP_LOOP - Hard constraints flag, base pair encloses hairpin loop.
• VRNA_CONSTRAINT_CONTEXT_INT_LOOP - Hard constraints flag, base pair encloses an interior loop.
• VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC - Hard constraints flag, base pair encloses a multi branch loop.
• VRNA_CONSTRAINT_CONTEXT_MB_LOOP - Hard constraints flag, base pair is enclosed in an interior loop.
• VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC - Hard constraints flag, base pair is enclosed in a multi branch loop.
• VRNA_CONSTRAINT_CONTEXT_ENFORCE - Hard constraint flag to indicate enforcement of constraints.
• VRNA_CONSTRAINT_CONTEXT_NO_REMOVE - Hard constraint flag to indicate not to remove base pairs that conflict with a given constraint.
• VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS - Constraint context flag indicating any loop context.

However, for Soft Constraints we do not allow for simple loop type dependent constraining. But soft constraints are equipped with generic constraint support. This enables the user to pass arbitrary callback functions that return auxiliary energy contributions for evaluation the evaluation of any decomposition.

The callback will then always be notified about the type of decomposition that is happening, and the corresponding delimiting sequence positions. The following decomposition steps are distinguished, and should be captured by the user's implementation of the callback:

• VRNA_DECOMP_PAIR_HP - Flag passed to generic softt constraints callback to indicate hairpin loop decomposition step.
• VRNA_DECOMP_PAIR_IL - Indicator for interior loop decomposition step.
• VRNA_DECOMP_PAIR_ML - Indicator for multibranch loop decomposition step.
• VRNA_DECOMP_ML_ML_ML - Indicator for decomposition of multibranch loop part.
• VRNA_DECOMP_ML_STEM - Indicator for decomposition of multibranch loop part.
• VRNA_DECOMP_ML_ML - Indicator for decomposition of multibranch loop part.
• VRNA_DECOMP_ML_UP - Indicator for decomposition of multibranch loop part.
• VRNA_DECOMP_ML_ML_STEM - Indicator for decomposition of multibranch loop part.
• VRNA_DECOMP_ML_COAXIAL - Indicator for decomposition of multibranch loop part.
• VRNA_DECOMP_EXT_EXT - Indicator for decomposition of exterior loop part.
• VRNA_DECOMP_EXT_UP - Indicator for decomposition of exterior loop part.
• VRNA_DECOMP_EXT_STEM - Indicator for decomposition of exterior loop part.
• VRNA_DECOMP_EXT_EXT_EXT - Indicator for decomposition of exterior loop part.
• VRNA_DECOMP_EXT_STEM_EXT - Indicator for decomposition of exterior loop part.
• VRNA_DECOMP_EXT_STEM_OUTSIDE - Indicator for decomposition of exterior loop part.
• VRNA_DECOMP_EXT_EXT_STEM - Indicator for decomposition of exterior loop part.
• VRNA_DECOMP_EXT_EXT_STEM1 - Indicator for decomposition of exterior loop part.

Simplified interfaces to the soft constraints framework can be obtained by the implementations in the submodules

• SHAPE Reactivity Data and
• ligands.

An implementation that generates soft constraints for unpaired nucleotides by minimizing the discrepancy between their predicted and expected pairing probability is available in submodule Generate Soft Constraints from Data.

Collaboration diagram for Constraining the RNA Folding Grammar:

Modules
	Hard Constraints
	This module covers all functionality for hard constraints in secondary structure prediction.
	Soft Constraints
	Functions and data structures for secondary structure soft constraints.

Files
file	basic.h
	Functions and data structures for constraining secondary structure predictions and evaluation.

Macros
#define	VRNA_CONSTRAINT_FILE   0
	Flag for vrna_constraints_add() to indicate that constraints are present in a text file. More...
#define	VRNA_CONSTRAINT_SOFT_MFE   0
	Indicate generation of constraints for MFE folding. More...
#define	VRNA_CONSTRAINT_SOFT_PF   VRNA_OPTION_PF
	Indicate generation of constraints for partition function computation. More...
#define	VRNA_DECOMP_PAIR_HP   (unsigned char)1
	Flag passed to generic softt constraints callback to indicate hairpin loop decomposition step. More...
#define	VRNA_DECOMP_PAIR_IL   (unsigned char)2
	Indicator for interior loop decomposition step. More...
#define	VRNA_DECOMP_PAIR_ML   (unsigned char)3
	Indicator for multibranch loop decomposition step. More...
#define	VRNA_DECOMP_ML_ML_ML   (unsigned char)5
	Indicator for decomposition of multibranch loop part. More...
#define	VRNA_DECOMP_ML_STEM   (unsigned char)6
	Indicator for decomposition of multibranch loop part. More...
#define	VRNA_DECOMP_ML_ML   (unsigned char)7
	Indicator for decomposition of multibranch loop part. More...
#define	VRNA_DECOMP_ML_UP   (unsigned char)8
	Indicator for decomposition of multibranch loop part. More...
#define	VRNA_DECOMP_ML_ML_STEM   (unsigned char)9
	Indicator for decomposition of multibranch loop part. More...
#define	VRNA_DECOMP_ML_COAXIAL   (unsigned char)10
	Indicator for decomposition of multibranch loop part. More...
#define	VRNA_DECOMP_ML_COAXIAL_ENC   (unsigned char)11
	Indicator for decomposition of multibranch loop part. More...
#define	VRNA_DECOMP_EXT_EXT   (unsigned char)12
	Indicator for decomposition of exterior loop part. More...
#define	VRNA_DECOMP_EXT_UP   (unsigned char)13
	Indicator for decomposition of exterior loop part. More...
#define	VRNA_DECOMP_EXT_STEM   (unsigned char)14
	Indicator for decomposition of exterior loop part. More...
#define	VRNA_DECOMP_EXT_EXT_EXT   (unsigned char)15
	Indicator for decomposition of exterior loop part. More...
#define	VRNA_DECOMP_EXT_STEM_EXT   (unsigned char)16
	Indicator for decomposition of exterior loop part. More...
#define	VRNA_DECOMP_EXT_STEM_OUTSIDE   (unsigned char)17
	Indicator for decomposition of exterior loop part.
#define	VRNA_DECOMP_EXT_EXT_STEM   (unsigned char)18
	Indicator for decomposition of exterior loop part. More...
#define	VRNA_DECOMP_EXT_EXT_STEM1   (unsigned char)19
	Indicator for decomposition of exterior loop part. More...

Functions
void	vrna_constraints_add (vrna_fold_compound_t *vc, const char *constraint, unsigned int options)
	Add constraints to a vrna_fold_compound_t data structure. More...
void	vrna_message_constraint_options (unsigned int option)
	Print a help message for pseudo dot-bracket structure constraint characters to stdout. (constraint support is specified by option parameter) More...
void	vrna_message_constraint_options_all (void)
	Print structure constraint characters to stdout (full constraint support) More...

Macro Definition Documentation

#define VRNA_CONSTRAINT_FILE   0

#include <ViennaRNA/constraints/basic.h>

Flag for vrna_constraints_add() to indicate that constraints are present in a text file.

See also

vrna_constraints_add()

Deprecated:

Use 0 instead!

#define VRNA_CONSTRAINT_SOFT_MFE   0

#include <ViennaRNA/constraints/basic.h>

Indicate generation of constraints for MFE folding.

Deprecated:

This flag has no meaning anymore, since constraints are now always stored!

#define VRNA_CONSTRAINT_SOFT_PF   VRNA_OPTION_PF

#include <ViennaRNA/constraints/basic.h>

Indicate generation of constraints for partition function computation.

Deprecated:

Use VRNA_OPTION_PF instead!

#define VRNA_DECOMP_PAIR_HP   (unsigned char)1

#include <ViennaRNA/constraints/basic.h>

Flag passed to generic softt constraints callback to indicate hairpin loop decomposition step.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates a hairpin loop enclosed by the base pair .

#define VRNA_DECOMP_PAIR_IL   (unsigned char)2

#include <ViennaRNA/constraints/basic.h>

Indicator for interior loop decomposition step.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates an interior loop enclosed by the base pair , and enclosing the base pair .

#define VRNA_DECOMP_PAIR_ML   (unsigned char)3

#include <ViennaRNA/constraints/basic.h>

Indicator for multibranch loop decomposition step.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates a multibranch loop enclosed by the base pair , and consisting of some enclosed multi loop content from k to l.

#define VRNA_DECOMP_ML_ML_ML   (unsigned char)5

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of multibranch loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates a multibranch loop part in the interval , which will be decomposed into two multibranch loop parts , and .

#define VRNA_DECOMP_ML_STEM   (unsigned char)6

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of multibranch loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates a multibranch loop part in the interval , which will be considered a single stem branching off with base pair .

#define VRNA_DECOMP_ML_ML   (unsigned char)7

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of multibranch loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates a multibranch loop part in the interval , which will be decomposed into a (usually) smaller multibranch loop part .

#define VRNA_DECOMP_ML_UP   (unsigned char)8

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of multibranch loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates a multibranch loop part in the interval , which will be considered a multibranch loop part that only consists of unpaired nucleotides.

#define VRNA_DECOMP_ML_ML_STEM   (unsigned char)9

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of multibranch loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates a multibranch loop part in the interval , which will decomposed into a multibranch loop part , and a stem with enclosing base pair .

#define VRNA_DECOMP_ML_COAXIAL   (unsigned char)10

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of multibranch loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates a multibranch loop part in the interval , where two stems with enclosing pairs and are coaxially stacking onto each other.

#define VRNA_DECOMP_ML_COAXIAL_ENC   (unsigned char)11

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of multibranch loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates a multibranch loop part in the interval , where two stems with enclosing pairs and are coaxially stacking onto each other.

#define VRNA_DECOMP_EXT_EXT   (unsigned char)12

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of exterior loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates an exterior loop part in the interval , which will be decomposed into a (usually) smaller exterior loop part .

#define VRNA_DECOMP_EXT_UP   (unsigned char)13

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of exterior loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates an exterior loop part in the interval , which will be considered as an exterior loop component consisting of only unpaired nucleotides.

#define VRNA_DECOMP_EXT_STEM   (unsigned char)14

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of exterior loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates an exterior loop part in the interval , which will be considered a stem with enclosing pair .

#define VRNA_DECOMP_EXT_EXT_EXT   (unsigned char)15

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of exterior loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates an exterior loop part in the interval , which will be decomposed into two exterior loop parts and .

#define VRNA_DECOMP_EXT_STEM_EXT   (unsigned char)16

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of exterior loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates an exterior loop part in the interval , which will be decomposed into a stem branching off with base pair , and an exterior loop part .

#define VRNA_DECOMP_EXT_EXT_STEM   (unsigned char)18

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of exterior loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates an exterior loop part in the interval , which will be decomposed into an exterior loop part , and a stem branching off with base pair .

#define VRNA_DECOMP_EXT_EXT_STEM1   (unsigned char)19

#include <ViennaRNA/constraints/basic.h>

Indicator for decomposition of exterior loop part.

This flag notifies the soft or hard constraint callback function that the current decomposition step evaluates an exterior loop part in the interval , which will be decomposed into an exterior loop part , and a stem branching off with base pair .

Function Documentation

void vrna_constraints_add	(	vrna_fold_compound_t *	vc,
		const char *	constraint,
		unsigned int	options
	)

#include <ViennaRNA/constraints/basic.h>

Add constraints to a vrna_fold_compound_t data structure.

Use this function to add/update the hard/soft constraints The function allows for passing a string 'constraint' that can either be a filename that points to a constraints definition file or it may be a pseudo dot-bracket notation indicating hard constraints. For the latter, the user has to pass the VRNA_CONSTRAINT_DB option. Also, the user has to specify, which characters are allowed to be interpreted as constraints by passing the corresponding options via the third parameter.

See also

vrna_hc_init(), vrna_hc_add_up(), vrna_hc_add_up_batch(), vrna_hc_add_bp(), vrna_sc_init(), vrna_sc_set_up(), vrna_sc_set_bp(), vrna_sc_add_SHAPE_deigan(), vrna_sc_add_SHAPE_zarringhalam(), vrna_hc_free(), vrna_sc_free(), VRNA_CONSTRAINT_DB, VRNA_CONSTRAINT_DB_DEFAULT, VRNA_CONSTRAINT_DB_PIPE, VRNA_CONSTRAINT_DB_DOT, VRNA_CONSTRAINT_DB_X, VRNA_CONSTRAINT_DB_ANG_BRACK, VRNA_CONSTRAINT_DB_RND_BRACK, VRNA_CONSTRAINT_DB_INTRAMOL, VRNA_CONSTRAINT_DB_INTERMOL, VRNA_CONSTRAINT_DB_GQUAD

The following is an example for adding hard constraints given in pseudo dot-bracket notation. Here, vc is the vrna_fold_compound_t object, structure is a char array with the hard constraint in dot-bracket notation, and enforceConstraints is a flag indicating whether or not constraints for base pairs should be enforced instead of just doing a removal of base pair that conflict with the constraint.

      unsigned int constraint_options = VRNA_CONSTRAINT_DB_DEFAULT;

      if (enforceConstraints)
        constraint_options |= VRNA_CONSTRAINT_DB_ENFORCE_BP;

      if (canonicalBPonly)
        constraint_options |= VRNA_CONSTRAINT_DB_CANONICAL_BP;

      vrna_constraints_add(fc, (const char *)cstruc, constraint_options);

In constrat to the above, constraints may also be read from file:

    vrna_constraints_add(fc, constraints_file, VRNA_OPTION_DEFAULT);

See also

vrna_hc_add_from_db(), vrna_hc_add_up(), vrna_hc_add_up_batch() vrna_hc_add_bp_unspecific(), vrna_hc_add_bp()

Parameters

vc	The fold compound
constraint	A string with either the filename of the constraint definitions or a pseudo dot-bracket notation of the hard constraint. May be NULL.
options	The option flags

void vrna_message_constraint_options

(

unsigned int

option

)

#include <ViennaRNA/constraints/hard.h>

Print a help message for pseudo dot-bracket structure constraint characters to stdout. (constraint support is specified by option parameter)

Currently available options are:
VRNA_CONSTRAINT_DB_PIPE (paired with another base)
VRNA_CONSTRAINT_DB_DOT (no constraint at all)
VRNA_CONSTRAINT_DB_X (base must not pair)
VRNA_CONSTRAINT_DB_ANG_BRACK (paired downstream/upstream)
VRNA_CONSTRAINT_DB_RND_BRACK (base i pairs base j)
pass a collection of options as one value like this:

vrna_message_constraints(option_1 | option_2 | option_n) 

See also

vrna_message_constraint_options_all(), vrna_constraints_add(), VRNA_CONSTRAINT_DB, VRNA_CONSTRAINT_DB_PIPE, VRNA_CONSTRAINT_DB_DOT, VRNA_CONSTRAINT_DB_X, VRNA_CONSTRAINT_DB_ANG_BRACK, VRNA_CONSTRAINT_DB_RND_BRACK, VRNA_CONSTRAINT_DB_INTERMOL, VRNA_CONSTRAINT_DB_INTRAMOL

Parameters

option

Option switch that tells which constraint help will be printed

void vrna_message_constraint_options_all

(

void

)

#include <ViennaRNA/constraints/hard.h>

Print structure constraint characters to stdout (full constraint support)

See also

vrna_message_constraint_options(), vrna_constraints_add(), VRNA_CONSTRAINT_DB, VRNA_CONSTRAINT_DB_PIPE, VRNA_CONSTRAINT_DB_DOT, VRNA_CONSTRAINT_DB_X, VRNA_CONSTRAINT_DB_ANG_BRACK, VRNA_CONSTRAINT_DB_RND_BRACK, VRNA_CONSTRAINT_DB_INTERMOL, VRNA_CONSTRAINT_DB_INTRAMOL