Hard Constraints
Constraining the Secondary Structure Predictions and Evaluations

This module covers all functionality for hard constraints in secondary structure prediction. More...

Collaboration diagram for Hard Constraints:

## Files

file | constraints_hard.h
| Functions and data structures for handling of secondary structure hard constraints.

## Data Structures

struct | vrna_hc_s
| The hard constraints data structure. More...
struct | vrna_hc_up_s
| A single hard constraint for a single nucleotide. More...

## Macros

#define | VRNA_CONSTRAINT_DB 16384U
| Flag for vrna_constraints_add() to indicate that constraint is passed in pseudo dot-bracket notation. More...
#define | VRNA_CONSTRAINT_DB_ENFORCE_BP 32768U
| Switch for dot-bracket structure constraint to enforce base pairs. More...
#define | VRNA_CONSTRAINT_DB_PIPE 65536U
| Flag that is used to indicate the pipe '|' sign in pseudo dot-bracket notation of hard constraints. More...
#define | VRNA_CONSTRAINT_DB_DOT 131072U
| dot '.' switch for structure constraints (no constraint at all) More...
#define | VRNA_CONSTRAINT_DB_X 262144U
| 'x' switch for structure constraint (base must not pair) More...
#define | VRNA_CONSTRAINT_DB_RND_BRACK 1048576U
| round brackets '(',')' switch for structure constraint (base i pairs base j) More...
#define | VRNA_CONSTRAINT_DB_INTRAMOL 2097152U
| Flag that is used to indicate the character 'l' in pseudo dot-bracket notation of hard constraints. More...
#define | VRNA_CONSTRAINT_DB_INTERMOL 4194304U
| Flag that is used to indicate the character 'e' in pseudo dot-bracket notation of hard constraints. More...
#define | VRNA_CONSTRAINT_DB_GQUAD 8388608U
| '+' switch for structure constraint (base is involved in a gquad) More...
#define | VRNA_CONSTRAINT_DB_DEFAULT
| Switch for dot-bracket structure constraint with default symbols. More...
#define | VRNA_CONSTRAINT_CONTEXT_EXT_LOOP (char)0x01
| Hard constraints flag, base pair in the exterior loop.
#define | VRNA_CONSTRAINT_CONTEXT_HP_LOOP (char)0x02
| Hard constraints flag, base pair encloses hairpin loop.
#define | VRNA_CONSTRAINT_CONTEXT_INT_LOOP (char)0x04
| Hard constraints flag, base pair encloses an interior loop.
#define | VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC (char)0x08
| Hard constraints flag, base pair encloses a multi branch loop.
#define | VRNA_CONSTRAINT_CONTEXT_MB_LOOP (char)0x10
| Hard constraints flag, base pair is enclosed in an interior loop.
#define | VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC (char)0x20
| Hard constraints flag, base pair is enclosed in a multi branch loop.
#define | VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS
| Hard constraints flag, shortcut for all base pairs.

## Typedefs

typedef struct vrna_hc_s | vrna_hc_t
| Typename for the hard constraints data structure vrna_hc_s.
typedef struct vrna_hc_up_s | vrna_hc_up_t
| Typename for the single nucleotide hard constraint data structure vrna_hc_up_s.
typedef char( | vrna_callback_hc_evaluate) (int i, int j, int k, int l, char d, void *data)
| Callback to evaluate whether or not a particular decomposition step is contributing to the solution space. More...

## Functions

void | vrna_hc_init (vrna_fold_compound_t *vc)
| Initialize/Reset hard constraints to default values. More...
void | vrna_hc_add_up (vrna_fold_compound_t *vc, int i, char option)
| Make a certain nucleotide unpaired. More...
int | vrna_hc_add_up_batch (vrna_fold_compound_t *vc, vrna_hc_up_t *constraints)
| Apply a list of hard constraints for single nucleotides. More...
void | vrna_hc_add_bp (vrna_fold_compound_t *vc, int i, int j, char option)
| Favorize/Enforce a certain base pair (i,j) More...
void | vrna_hc_add_bp_nonspecific (vrna_fold_compound_t *vc, int i, int d, char option)
| Enforce a nucleotide to be paired (upstream/downstream) More...
void | vrna_hc_free (vrna_hc_t *hc)
| Free the memory allocated by a vrna_hc_t data structure. More...
int | vrna_hc_add_from_db (vrna_fold_compound_t *vc, const char *constraint, unsigned int options)
| Add hard constraints from pseudo dot-bracket notation. More...

## Detailed Description

This module covers all functionality for hard constraints in secondary structure prediction.

## Data Structure Documentation

struct vrna_hc_s

The hard constraints data structure.

The content of this data structure determines the decomposition pattern used in the folding recursions. Attribute 'matrix' is used as source for the branching pattern of the decompositions during all folding recursions. Any entry in matrix[i,j] consists of the 6 LSB that allows to distinguish the following types of base pairs:

- in the exterior loop (VRNA_CONSTRAINT_CONTEXT_EXT_LOOP)
- enclosing a hairpin (VRNA_CONSTRAINT_CONTEXT_HP_LOOP)
- enclosing an interior loop (VRNA_CONSTRAINT_CONTEXT_INT_LOOP)
- enclosed by an exterior loop (VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC)
- enclosing a multi branch loop (VRNA_CONSTRAINT_CONTEXT_MB_LOOP)
- enclosed by a multi branch loop (VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC)

The four linear arrays 'up_xxx' provide the number of available unpaired nucleotides (including position i) 3' of each position in the sequence.

See also
  vrna_hc_init(), vrna_hc_free(), VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, VRNA_CONSTRAINT_CONTEXT_HP_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP, #VRNA_CONSTRAINT_CONTEXT_EXT_LOOP_ENC, VRNA_CONSTRAINT_CONTEXT_MB_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC

### Data Fields

char * | matrix
| Upper triangular matrix that encodes where a base pair or unpaired nucleotide is allowed.
int * | up_ext
| A linear array that holds the number of allowed unpaired nucleotides in an exterior loop.
int * | up_hp
| A linear array that holds the number of allowed unpaired nucleotides in a hairpin loop.
int * | up_int
| A linear array that holds the number of allowed unpaired nucleotides in an interior loop.
int * | up_ml
| A linear array that holds the number of allowed unpaired nucleotides in a multi branched loop.
vrna_callback_hc_evaluate * | f
| A function pointer that returns whether or not a certain decomposition may be evaluated.
void * | data
| A pointer to some structure where the user may store necessary data to evaluate its generic hard constraint function.
vrna_callback_free_auxdata * | free_data
| A pointer to a function to free memory occupied by auxiliary data. More...

#### Field Documentation

vrna_callback_free_auxdata* vrna_hc_s::free_data

A pointer to a function to free memory occupied by auxiliary data.

The function this pointer is pointing to will be called upon destruction of the vrna_hc_s, and provided with the vrna_hc_s.data pointer that may hold auxiliary data. Hence, to avoid leaking memory, the user may use this pointer to free memory occupied by auxiliary data.

struct vrna_hc_up_s

A single hard constraint for a single nucleotide.

### Data Fields

int | position
| The sequence position (1-based)
char | options
| The hard constraint option.

## Macro Definition Documentation

#define VRNA_CONSTRAINT_DB 16384U

`#include <ViennaRNA/constraints_hard.h>`

Flag for vrna_constraints_add() to indicate that constraint is passed in pseudo dot-bracket notation.

See also
  vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

#define VRNA_CONSTRAINT_DB_ENFORCE_BP 32768U

`#include <ViennaRNA/constraints_hard.h>`

Switch for dot-bracket structure constraint to enforce base pairs.

This flag should be used to really enforce base pairs given in dot-bracket constraint rather than just weakly-enforcing them.

See also
  vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

#define VRNA_CONSTRAINT_DB_PIPE 65536U

`#include <ViennaRNA/constraints_hard.h>`

Flag that is used to indicate the pipe '|' sign in pseudo dot-bracket notation of hard constraints.

Use this definition to indicate the pipe sign '|' (paired with another base)

See also
  vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

#define VRNA_CONSTRAINT_DB_DOT 131072U

`#include <ViennaRNA/constraints_hard.h>`

dot '.' switch for structure constraints (no constraint at all)

See also
  vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

#define VRNA_CONSTRAINT_DB_X 262144U

`#include <ViennaRNA/constraints_hard.h>`

'x' switch for structure constraint (base must not pair)

See also
  vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

#define VRNA_CONSTRAINT_DB_RND_BRACK 1048576U

`#include <ViennaRNA/constraints_hard.h>`

round brackets '(',')' switch for structure constraint (base i pairs base j)

See also
  vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

#define VRNA_CONSTRAINT_DB_INTRAMOL 2097152U

`#include <ViennaRNA/constraints_hard.h>`

Flag that is used to indicate the character 'l' in pseudo dot-bracket notation of hard constraints.

Use this definition to indicate the usage of 'l' character (intramolecular pairs only)

See also
  vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

#define VRNA_CONSTRAINT_DB_INTERMOL 4194304U

`#include <ViennaRNA/constraints_hard.h>`

Flag that is used to indicate the character 'e' in pseudo dot-bracket notation of hard constraints.

Use this definition to indicate the usage of 'e' character (intermolecular pairs only)

See also
  vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

#define VRNA_CONSTRAINT_DB_GQUAD 8388608U

`#include <ViennaRNA/constraints_hard.h>`

'+' switch for structure constraint (base is involved in a gquad)

See also
  vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

Warning
  This flag is for future purposes only! No implementation recognizes it yet.

#define VRNA_CONSTRAINT_DB_DEFAULT

`#include <ViennaRNA/constraints_hard.h>`

Value:
( 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_INTRAMOL \
| VRNA_CONSTRAINT_DB_INTERMOL \
| VRNA_CONSTRAINT_DB_GQUAD \
)
VRNA_CONSTRAINT_DB_ANG_BRACK
#define VRNA_CONSTRAINT_DB_ANG_BRACK
angle brackets '<', '>' switch for structure constraint (paired downstream/upstream) ...
Definition: constraints_hard.h:138
VRNA_CONSTRAINT_DB_GQUAD
#define VRNA_CONSTRAINT_DB_GQUAD
'+' switch for structure constraint (base is involved in a gquad)
Definition: constraints_hard.h:185
VRNA_CONSTRAINT_DB_DOT
#define VRNA_CONSTRAINT_DB_DOT
dot '.' switch for structure constraints (no constraint at all)
Definition: constraints_hard.h:122
VRNA_CONSTRAINT_DB_PIPE
#define VRNA_CONSTRAINT_DB_PIPE
Flag that is used to indicate the pipe '|' sign in pseudo dot-bracket notation of hard constraints...
Definition: constraints_hard.h:112
VRNA_CONSTRAINT_DB
#define VRNA_CONSTRAINT_DB
Flag for vrna_constraints_add() to indicate that constraint is passed in pseudo dot-bracket notation...
Definition: constraints_hard.h:86
VRNA_CONSTRAINT_DB_X
#define VRNA_CONSTRAINT_DB_X
'x' switch for structure constraint (base must not pair)
Definition: constraints_hard.h:131
VRNA_CONSTRAINT_DB_INTRAMOL
#define VRNA_CONSTRAINT_DB_INTRAMOL
Flag that is used to indicate the character 'l' in pseudo dot-bracket notation of hard constraints...
Definition: constraints_hard.h:160
VRNA_CONSTRAINT_DB_RND_BRACK
#define VRNA_CONSTRAINT_DB_RND_BRACK
round brackets '(',')' switch for structure constraint (base i pairs base j)
Definition: constraints_hard.h:147
VRNA_CONSTRAINT_DB_INTERMOL
#define VRNA_CONSTRAINT_DB_INTERMOL
Flag that is used to indicate the character 'e' in pseudo dot-bracket notation of hard constraints...
Definition: constraints_hard.h:173

Switch for dot-bracket structure constraint with default symbols.

This flag conveniently combines all possible symbols in dot-bracket notation for hard constraints and VRNA_CONSTRAINT_DB

See also
  vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

## Typedef Documentation

typedef char( vrna_callback_hc_evaluate) (int i, int j, int k, int l, char d, void *data)

`#include <ViennaRNA/constraints_hard.h>`

Callback to evaluate whether or not a particular decomposition step is contributing to the solution space.

This is the prototype for callback functions used by the folding recursions to evaluate generic hard constraints. The first four parameters passed indicate the delimiting nucleotide positions of the decomposition, and the parameter `denotes` the decomposition step. The last parameter `data` is the auxiliary data structure associated to the hard constraints via vrna_hc_add_data(), or NULL if no auxiliary data was added.

See also
  VRNA_DECOMP_PAIR_HP, VRNA_DECOMP_PAIR_IL, VRNA_DECOMP_PAIR_ML, VRNA_DECOMP_ML_ML_ML, VRNA_DECOMP_ML_STEM, VRNA_DECOMP_ML_ML, VRNA_DECOMP_ML_UP, VRNA_DECOMP_ML_ML_STEM, VRNA_DECOMP_ML_COAXIAL, VRNA_DECOMP_EXT_EXT, VRNA_DECOMP_EXT_UP, VRNA_DECOMP_EXT_STEM, VRNA_DECOMP_EXT_EXT_EXT, VRNA_DECOMP_EXT_STEM_EXT, VRNA_DECOMP_EXT_EXT_STEM, VRNA_DECOMP_EXT_EXT_STEM1, vrna_hc_add_f(), vrna_hc_add_data()

Parameters

  i | Left (5') delimiter position of substructure
  j | Right (3') delimiter position of substructure
  k | Left delimiter of decomposition
  l | Right delimiter of decomposition
  d | Decomposition step indicator
  data | Auxiliary data

Returns
  Pseudo energy contribution in deka-kalories per mol

## Function Documentation

void vrna_hc_init | ( | vrna_fold_compound_t * | vc | ) |

`#include <ViennaRNA/constraints_hard.h>`

Initialize/Reset hard constraints to default values.

This function resets the hard constraints to their default values, i.e. all positions may be unpaired in all contexts, and base pairs are allowed in all contexts, if they resemble canonical pairs. Previously set hard constraints will be removed vefore initialization.

See also
  vrna_hc_add_bp(), vrna_hc_add_bp_nonspecific(), vrna_hc_add_up()

Parameters

  vc | The fold compound

void vrna_hc_add_up | ( | vrna_fold_compound_t * | vc,
|  | int | i,
|  | char | option
| ) |  |

`#include <ViennaRNA/constraints_hard.h>`

Make a certain nucleotide unpaired.

See also
  vrna_hc_add_bp(), vrna_hc_add_bp_nonspecific(), vrna_hc_init(), VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, VRNA_CONSTRAINT_CONTEXT_HP_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP, VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS

Parameters

  vc | The vrna_fold_compound_t the hard constraints are associated with
  i | The position that needs to stay unpaired (1-based)
  option | The options flag indicating how/where to store the hard constraints

int vrna_hc_add_up_batch | ( | vrna_fold_compound_t * | vc,
|  | vrna_hc_up_t * | constraints
| ) |  |

`#include <ViennaRNA/constraints_hard.h>`

Apply a list of hard constraints for single nucleotides.

Parameters

  vc | The vrna_fold_compound_t the hard constraints are associated with
  constraints | The list off constraints to apply, last entry must have position attribute set to 0

void vrna_hc_add_bp | ( | vrna_fold_compound_t * | vc,
|  | int | i,
|  | int | j,
|  | char | option
| ) |  |

`#include <ViennaRNA/constraints_hard.h>`

Favorize/Enforce a certain base pair (i,j)

See also
  vrna_hc_add_bp_nonspecific(), vrna_hc_add_up(), vrna_hc_init(), VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, VRNA_CONSTRAINT_CONTEXT_HP_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC, VRNA_CONSTRAINT_CONTEXT_MB_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC, #VRNA_CONSTRAINT_CONTEXT_ENFORCE, VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS

Parameters

  vc | The vrna_fold_compound_t the hard constraints are associated with
  i | The 5' located nucleotide position of the base pair (1-based)
  j | The 3' located nucleotide position of the base pair (1-based)
  option | The options flag indicating how/where to store the hard constraints

void vrna_hc_add_bp_nonspecific | ( | vrna_fold_compound_t * | vc,
|  | int | i,
|  | int | d,
|  | char | option
| ) |  |

`#include <ViennaRNA/constraints_hard.h>`

Enforce a nucleotide to be paired (upstream/downstream)

See also
  vrna_hc_add_bp(), vrna_hc_add_up(), vrna_hc_init(), VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, VRNA_CONSTRAINT_CONTEXT_HP_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC, VRNA_CONSTRAINT_CONTEXT_MB_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC, VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS

Parameters

  vc | The vrna_fold_compound_t the hard constraints are associated with
  i | The position that needs to stay unpaired (1-based)
  d | The direction of base pairing ( : pairs upstream, : pairs downstream, : no direction)
  option | The options flag indicating in which loop type context the pairs may appear

void vrna_hc_free | ( | vrna_hc_t * | hc | ) |

`#include <ViennaRNA/constraints_hard.h>`

Free the memory allocated by a vrna_hc_t data structure.

Use this function to free all memory that was allocated for a data structure of type vrna_hc_t .

See also
  get_hard_constraints(), vrna_hc_t

int vrna_hc_add_from_db | ( | vrna_fold_compound_t * | vc,
|  | const char * | constraint,
|  | unsigned int | options
| ) |  |

`#include <ViennaRNA/constraints_hard.h>`

Add hard constraints from pseudo dot-bracket notation.

This function allows one to apply hard constraints from a pseudo dot-bracket notation. The `options` parameter controls, which characters are recognized by the parser. Use the VRNA_CONSTRAINT_DB_DEFAULT convenience macro, if you want to allow all known characters

See also
  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

Parameters

  vc | The fold compound
  constraint | A pseudo dot-bracket notation of the hard constraint.
  options | The option flags