Hard Constraints

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

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 interior 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 interior 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, 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_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, int i, 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

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

Public Members

vrna_hc_type_e type

unsigned int n

unsigned char state

unsigned char *mx

unsigned char **matrix_local

union vrna_hc_s.[anonymous] [anonymous]

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_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