Hard Constraints

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

Introduction 

Hard constraints as implemented in our library can be specified for individual loop types, i.e. the atomic derivations of the RNA folding grammar rules. Hence, the pairing behavior of both, single nucleotides and pairs of bases, can be constrained in every loop context separately. Additionally, an abstract implementation using a callback mechanism allows for full control of more complex hard constraints.

Hard Constraints API 

Defines

VRNA_CONSTRAINT_DB

#include <ViennaRNA/constraints/hard.h>

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

VRNA_CONSTRAINT_DB_ENFORCE_BP

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

VRNA_CONSTRAINT_DB_PIPE

#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)

VRNA_CONSTRAINT_DB_DOT

#include <ViennaRNA/constraints/hard.h>

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

VRNA_CONSTRAINT_DB_X

#include <ViennaRNA/constraints/hard.h>

‘x’ switch for structure constraint (base must not pair)

VRNA_CONSTRAINT_DB_RND_BRACK

#include <ViennaRNA/constraints/hard.h>

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

VRNA_CONSTRAINT_DB_INTRAMOL

#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)

VRNA_CONSTRAINT_DB_INTERMOL

#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)

VRNA_CONSTRAINT_DB_GQUAD

#include <ViennaRNA/constraints/hard.h>

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

Warning

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

VRNA_CONSTRAINT_DB_WUSS

#include <ViennaRNA/constraints/hard.h>

Flag to indicate Washington University Secondary Structure (WUSS) notation of the hard constraint string.

This secondary structure notation for RNAs is usually used as consensus secondary structure (SS_cons) entry in Stockholm formatted files

VRNA_CONSTRAINT_DB_DEFAULT

#include <ViennaRNA/constraints/hard.h>

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

VRNA_CONSTRAINT_CONTEXT_EXT_LOOP: #include <ViennaRNA/constraints/hard.h>
Hard constraints flag, base pair in the exterior loop.

VRNA_CONSTRAINT_CONTEXT_HP_LOOP: #include <ViennaRNA/constraints/hard.h>
Hard constraints flag, base pair encloses hairpin loop.

VRNA_CONSTRAINT_CONTEXT_INT_LOOP: #include <ViennaRNA/constraints/hard.h>
Hard constraints flag, base pair encloses an internal loop.

VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC: #include <ViennaRNA/constraints/hard.h>
Hard constraints flag, base pair encloses a multi branch loop.

VRNA_CONSTRAINT_CONTEXT_MB_LOOP: #include <ViennaRNA/constraints/hard.h>
Hard constraints flag, base pair is enclosed in an internal loop.

VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC: #include <ViennaRNA/constraints/hard.h>
Hard constraints flag, base pair is enclosed in a multi branch loop.

VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS: #include <ViennaRNA/constraints/hard.h>
Constraint context flag indicating any loop context.

Typedefs

typedef struct vrna_hc_s vrna_hc_t: #include <ViennaRNA/constraints/hard.h>
Typename for the hard constraints data structure vrna_hc_s.

typedef struct vrna_hc_up_s vrna_hc_up_t: #include <ViennaRNA/constraints/hard.h>
Typename for the single nucleotide hard constraint data structure vrna_hc_up_s.

typedef unsigned char (*vrna_hc_eval_f)(int i, int j, int k, int l, unsigned 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.

Notes on Callback Functions:: This callback enables one to over-rule default hard constraints in secondary structure decompositions.

Param i:: Left (5’) delimiter position of substructure
Param j:: Right (3’) delimiter position of substructure
Param k:: Left delimiter of decomposition
Param l:: Right delimiter of decomposition
Param d:: Decomposition step indicator
Param data:: Auxiliary data
Return:: A non-zero value if the decomposition is valid, 0 otherwise

Functions

void vrna_constraints_add(vrna_fold_compound_t *fc, 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.

The following is an example for adding hard constraints given in pseudo dot-bracket notation. Here, fc 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);

Parameters:

fc – 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_hc_init(vrna_fold_compound_t *fc)

#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 before initialization.

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

Parameters:

fc – The fold compound

void vrna_hc_add_up(vrna_fold_compound_t *fc, unsigned int i, unsigned char option)

#include <ViennaRNA/constraints/hard.h>

Make a certain nucleotide unpaired.

Parameters:

fc – 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_strand(vrna_fold_compound_t *fc, unsigned int i, int strand, unsigned char option)

#include <ViennaRNA/constraints/hard.h>

Make a certain nucleotide unpaired.

This function puts a constraint onto a single nucleotide to limit or enforce its structural context. The position i should be given in local coordinates relative to the strand strand it corresponds to.

Note

A negative value for the strand number strand indicates autodetection of the strand number assuming that coordinate i is given as global coordinates for the (current) concatenation of all strands. In this case, the function behaves exactly as vrna_hc_add_up().

Parameters:

fc – The vrna_fold_compound_t the hard constraints are associated with
i – The position that needs to stay unpaired (1-based)
strand – The strand number of nucleotide i (0-based, negative value for autodetect)
option – The options flag indicating how/where to store the hard constraints

int vrna_hc_add_up_batch(vrna_fold_compound_t *fc, vrna_hc_up_t *constraints)

#include <ViennaRNA/constraints/hard.h>

Apply a list of hard constraints for single nucleotides.

Parameters:

fc – 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

int vrna_hc_add_bp(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, unsigned char option)

#include <ViennaRNA/constraints/hard.h>

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

Parameters:

fc – 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

int vrna_hc_add_bp_strand(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, int strand_i, int strand_j, unsigned char option)

#include <ViennaRNA/constraints/hard.h>

Favorize/Enforce a certain base pair (i,j) where i and j may point to different strands.

This function adds a base pair constraint for pair (i,j), where the positions i and j are relative to the RNA strands i and j correspond to. For each strand strand_i and @strand_j positions are 1-based. For instance, if position 5 of strand 0 must pair with position 10 of strand 1, the function call would be

vrna_hc_add_bp(fc, 5, 10, 0, 1, VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS | VRNA_CONSTRAINT_CONTEXT_ENFORCE);

Negative values for the strand numbers strand_i and strand_j indicate autodetection of the strand number assuming that coordinates i and/or j are given as global coordinates for the (current) concatenation of all strands

Parameters:

fc – The vrna_fold_compound_t the hard constraints are associated with
i – The 5’ located nucleotide position of the base pair (1-based, relative to strand_i)
j – The 3’ located nucleotide position of the base pair (1-based, relative to strand_j)
strand_i – The strand number of pairing partner i (0-based, negative value for autodetect)
strand_i – The strand number of pairing partner j (0-based, negative value for autodetect)
option – The option flag(s) indicating loop types and enforcement of the constraint

void vrna_hc_add_bp_nonspecific(vrna_fold_compound_t *fc, unsigned int i, int d, unsigned char option)

#include <ViennaRNA/constraints/hard.h>

Enforce a nucleotide to be paired (upstream/downstream)

Parameters:

fc – 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 ( \( d < 0 \): pairs upstream, \( d > 0 \): pairs downstream, \( d == 0 \): 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 *fc, 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

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

Parameters:

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

struct vrna_hc_s

#include <ViennaRNA/constraints/hard.h>

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

Public Members

vrna_hc_type_e type

unsigned int n

unsigned char state

unsigned char *mx

unsigned char **matrix_local

unsigned int *up_ext: A linear array that holds the number of allowed unpaired nucleotides in an exterior loop.

unsigned int *up_hp: A linear array that holds the number of allowed unpaired nucleotides in a hairpin loop.

unsigned int *up_int: A linear array that holds the number of allowed unpaired nucleotides in an internal loop.

unsigned int *up_ml: A linear array that holds the number of allowed unpaired nucleotides in a multi branched loop.

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

vrna_hc_depot_t *depot

struct vrna_hc_up_s

#include <ViennaRNA/constraints/hard.h>

A single hard constraint for a single nucleotide.

Public Members

int position: The sequence position (1-based)

int strand

unsigned char options: The hard constraint option

Hard Constraints

Introduction

Hard Constraints API

Introduction 

Hard Constraints API 