The Fold Compound

This module provides interfaces that deal with the most basic data structure used in structure predicting and energy evaluating function of the RNAlib.

Throughout the entire RNAlib, the vrna_fold_compound_t, is used to group information and data that is required for structure prediction and energy evaluation. Here, you’ll find interface functions to create, modify, and delete vrna_fold_compound_t data structures.

Defines

VRNA_STATUS_MFE_PRE

#include <ViennaRNA/fold_compound.h>

Status message indicating that MFE computations are about to begin.

VRNA_STATUS_MFE_POST

#include <ViennaRNA/fold_compound.h>

Status message indicating that MFE computations are finished.

VRNA_STATUS_PF_PRE

#include <ViennaRNA/fold_compound.h>

Status message indicating that Partition function computations are about to begin.

VRNA_STATUS_PF_POST

#include <ViennaRNA/fold_compound.h>

Status message indicating that Partition function computations are finished.

VRNA_OPTION_DEFAULT: #include <ViennaRNA/fold_compound.h>
Option flag to specify default settings/requirements.

VRNA_OPTION_MFE

#include <ViennaRNA/fold_compound.h>

Option flag to specify requirement of Minimum Free Energy (MFE) DP matrices and corresponding set of energy parameters.

VRNA_OPTION_PF

#include <ViennaRNA/fold_compound.h>

Option flag to specify requirement of Partition Function (PF) DP matrices and corresponding set of Boltzmann factors.

VRNA_OPTION_HYBRID: #include <ViennaRNA/fold_compound.h>
Option flag to specify requirement of dimer DP matrices.

VRNA_OPTION_EVAL_ONLY

#include <ViennaRNA/fold_compound.h>

Option flag to specify that neither MFE, nor PF DP matrices are required.

Use this flag in conjuntion with VRNA_OPTION_MFE, and VRNA_OPTION_PF to save memory for a vrna_fold_compound_t obtained from vrna_fold_compound(), or vrna_fold_compound_comparative() in cases where only energy evaluation but no structure prediction is required.

VRNA_OPTION_WINDOW: #include <ViennaRNA/fold_compound.h>
Option flag to specify requirement of DP matrices for local folding approaches.

VRNA_OPTION_F5: #include <ViennaRNA/fold_compound.h>

VRNA_OPTION_F3: #include <ViennaRNA/fold_compound.h>

VRNA_OPTION_WINDOW_F5: #include <ViennaRNA/fold_compound.h>

VRNA_OPTION_WINDOW_F3: #include <ViennaRNA/fold_compound.h>

Typedefs

typedef struct vrna_fc_s vrna_fold_compound_t: #include <ViennaRNA/fold_compound.h>
Typename for the fold_compound data structure vrna_fc_s.

typedef void (*vrna_auxdata_free_f)(void *data)

#include <ViennaRNA/fold_compound.h>

Callback to free memory allocated for auxiliary user-provided data.

This type of user-implemented function usually deletes auxiliary data structures. The user must take care to free all the memory occupied by the data structure passed.

Notes on Callback Functions:: This callback is supposed to free memory occupied by an auxiliary data structure. It will be called when the vrna_fold_compound_t is erased from memory through a call to vrna_fold_compound_free() and will be passed the address of memory previously bound to the vrna_fold_compound_t via vrna_fold_compound_add_auxdata().

Param data:: The data that needs to be free’d

typedef int (*vrna_auxdata_prepare_f)(vrna_fold_compound_t *fc, void *data, unsigned int event, void *event_data): #include <ViennaRNA/fold_compound.h>

void() vrna_callback_free_auxdata (void *data)

#include <ViennaRNA/fold_compound.h>

Callback to free memory allocated for auxiliary user-provided data.

Deprecated:: Use vrna_auxdata_free_f(void *data) instead!

typedef void (*vrna_recursion_status_f)(unsigned char status, void *data)

#include <ViennaRNA/fold_compound.h>

Callback to perform specific user-defined actions before, or after recursive computations.

Notes on Callback Functions:: This function will be called to notify a third-party implementation about the status of a currently ongoing recursion. The purpose of this callback mechanism is to provide users with a simple way to ensure pre- and post conditions for auxiliary mechanisms attached to our implementations.

Param status:: The status indicator
Param data:: The data structure that was assigned with vrna_fold_compound_add_auxdata()

void() vrna_callback_recursion_status (unsigned char status, void *data): #include <ViennaRNA/fold_compound.h>

Enums

enum vrna_fc_type_e

An enumerator that is used to specify the type of a vrna_fold_compound_t.

Values:

enumerator VRNA_FC_TYPE_SINGLE: Type is suitable for single, and hybridizing sequences

enumerator VRNA_FC_TYPE_COMPARATIVE: Type is suitable for sequence alignments (consensus structure prediction)

Functions

vrna_fold_compound_t *vrna_fold_compound(const char *sequence, const vrna_md_t *md_p, unsigned int options)

#include <ViennaRNA/fold_compound.h>

Retrieve a vrna_fold_compound_t data structure for single sequences and hybridizing sequences.

This function provides an easy interface to obtain a prefilled vrna_fold_compound_t by passing a single sequence, or two contatenated sequences as input. For the latter, sequences need to be seperated by an ‘&’ character like this:

char *sequence = "GGGG&CCCC";

The optional parameter md_p can be used to specify the model details for successive computations based on the content of the generated vrna_fold_compound_t. Passing NULL will instruct the function to use default model details. The third parameter options may be used to specify dynamic programming (DP) matrix requirements.

Options

VRNA_OPTION_DEFAULT - Option flag to specify default settings/requirements.
VRNA_OPTION_MFE - Option flag to specify requirement of Minimum Free Energy (MFE) DP matrices and corresponding set of energy parameters.
VRNA_OPTION_PF - Option flag to specify requirement of Partition Function (PF) DP matrices and corresponding set of Boltzmann factors.
VRNA_OPTION_WINDOW - Option flag to specify requirement of DP matrices for local folding approaches.

The above options may be OR-ed together.

If you just need the folding compound serving as a container for your data, you can simply pass VRNA_OPTION_DEFAULT to the option parameter. This creates a vrna_fold_compound_t without DP matrices, thus saving memory. Subsequent calls of any structure prediction function will then take care of allocating the memory required for the DP matrices. If you only intend to evaluate structures instead of actually predicting them, you may use the VRNA_OPTION_EVAL_ONLY macro. This will seriously speedup the creation of the vrna_fold_compound_t.

Note

The sequence string must be uppercase, and should contain only RNA (resp. DNA) alphabet depending on what energy parameter set is used

Parameters:

sequence – A single sequence, or two concatenated sequences seperated by an ‘&’ character
md_p – An optional set of model details
options – The options for DP matrices memory allocation

Returns:

A prefilled vrna_fold_compound_t ready to be used for computations (may be NULL on error)

vrna_fold_compound_t *vrna_fold_compound_comparative(const char **sequences, vrna_md_t *md_p, unsigned int options)

#include <ViennaRNA/fold_compound.h>

Retrieve a vrna_fold_compound_t data structure for sequence alignments.

This function provides an easy interface to obtain a prefilled vrna_fold_compound_t by passing an alignment of sequences.

The optional parameter md_p can be used to specify the model details for successive computations based on the content of the generated vrna_fold_compound_t. Passing NULL will instruct the function to use default model details. The third parameter options may be used to specify dynamic programming (DP) matrix requirements.

Options

VRNA_OPTION_DEFAULT - Option flag to specify default settings/requirements.
VRNA_OPTION_MFE - Option flag to specify requirement of Minimum Free Energy (MFE) DP matrices and corresponding set of energy parameters.
VRNA_OPTION_PF - Option flag to specify requirement of Partition Function (PF) DP matrices and corresponding set of Boltzmann factors.
VRNA_OPTION_WINDOW - Option flag to specify requirement of DP matrices for local folding approaches.

The above options may be OR-ed together.

If you just need the folding compound serving as a container for your data, you can simply pass VRNA_OPTION_DEFAULT to the option parameter. This creates a vrna_fold_compound_t without DP matrices, thus saving memory. Subsequent calls of any structure prediction function will then take care of allocating the memory required for the DP matrices. If you only intend to evaluate structures instead of actually predicting them, you may use the VRNA_OPTION_EVAL_ONLY macro. This will seriously speedup the creation of the vrna_fold_compound_t.

Note

The sequence strings must be uppercase, and should contain only RNA (resp. DNA) alphabet including gap characters depending on what energy parameter set is used.

Parameters:

sequences – A sequence alignment including ‘gap’ characters
md_p – An optional set of model details
options – The options for DP matrices memory allocation

Returns:

A prefilled vrna_fold_compound_t ready to be used for computations (may be NULL on error)

vrna_fold_compound_t *vrna_fold_compound_comparative2(const char **sequences, const char **names, const unsigned char *orientation, const unsigned long long *start, const unsigned long long *genome_size, vrna_md_t *md_p, unsigned int options): #include <ViennaRNA/fold_compound.h>

vrna_fold_compound_t *vrna_fold_compound_TwoD(const char *sequence, const char *s1, const char *s2, vrna_md_t *md_p, unsigned int options): #include <ViennaRNA/fold_compound.h>

int vrna_fold_compound_prepare(vrna_fold_compound_t *fc, unsigned int options): #include <ViennaRNA/fold_compound.h>

void vrna_fold_compound_free(vrna_fold_compound_t *fc)

#include <ViennaRNA/fold_compound.h>

Free memory occupied by a vrna_fold_compound_t.

Parameters:

fc – The vrna_fold_compound_t that is to be erased from memory

void vrna_fold_compound_add_auxdata(vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f f)

#include <ViennaRNA/fold_compound.h>

Add auxiliary data to the vrna_fold_compound_t.

This function allows one to bind arbitrary data to a vrna_fold_compound_t which may later on be used by one of the callback functions, e.g. vrna_recursion_status_f(). To allow for proper cleanup of the memory occupied by this auxiliary data, the user may also provide a pointer to a cleanup function that free’s the corresponding memory. This function will be called automatically when the vrna_fold_compound_t is free’d with vrna_fold_compound_free().

See also

vrna_auxdata_free_f()

Note

Before attaching the arbitrary data pointer, this function will call the vrna_auxdata_free_f() on any pre-existing data that is already attached.

Parameters:

fc – The fold_compound the arbitrary data pointer should be associated with
data – A pointer to an arbitrary data structure
f – A pointer to function that free’s memory occupied by the arbitrary data (May be NULL)

void vrna_fold_compound_add_callback(vrna_fold_compound_t *fc, vrna_recursion_status_f f)

#include <ViennaRNA/fold_compound.h>

Add a recursion status callback to the vrna_fold_compound_t.

Binding a recursion status callback function to a vrna_fold_compound_t allows one to perform arbitrary operations just before, or after an actual recursive computations, e.g. MFE prediction, is performed by the RNAlib. The callback function will be provided with a pointer to its vrna_fold_compound_t, and a status message. Hence, it has complete access to all variables that incluence the recursive computations.

Parameters:

fc – The fold_compound the callback function should be attached to
f – The pointer to the recursion status callback function

struct vrna_fc_s

#include <ViennaRNA/fold_compound.h>

The most basic data structure required by many functions throughout the RNAlib.

SWIG Wrapper Notes:

This data structure is wrapped as class fold_compound with several related functions attached as methods.

A new fold_compound can be obtained by calling one of its constructors:

fold_compound(seq) - Initialize with a single sequence, or two concatenated sequences separated by an ampersand character & (for cofolding)
fold_compound(aln) - Initialize with a sequence alignment aln stored as a list of sequences (with gap characters).

The resulting object has a list of attached methods which in most cases directly correspond to functions that mainly operate on the corresponding C data structure:

type() - Get the type of the fold_compound (See vrna_fc_type_e)
length() - Get the length of the sequence(s) or alignment stored within the fold_compound.

See, e.g. RNA.fold_compound in the Python API.

Note

Please read the documentation of this data structure carefully! Some attributes are only available for specific types this data structure can adopt.

Warning

Reading/Writing from/to attributes that are not within the scope of the current type usually result in undefined behavior!

Common data fields

const vrna_fc_type_e type

The type of the vrna_fold_compound_t.

Currently possible values are VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE

Warning

Do not edit this attribute, it will be automagically set by the corresponding get() methods for the vrna_fold_compound_t. The value specified in this attribute dictates the set of other attributes to use within this data structure.

unsigned int length: The length of the sequence (or sequence alignment)

int cutpoint: The position of the (cofold) cutpoint within the provided sequence. If there is no cutpoint, this field will be set to -1.

unsigned int *strand_number: The strand number a particular nucleotide is associated with.

unsigned int *strand_order: The strand order, i.e. permutation of current concatenated sequence.

unsigned int *strand_order_uniq: The strand order array where identical sequences have the same ID.

unsigned int *strand_start: The start position of a particular strand within the current concatenated sequence.

unsigned int *strand_end: The end (last) position of a particular strand within the current concatenated sequence.

unsigned int strands: Number of interacting strands.

vrna_seq_t *nucleotides: Set of nucleotide sequences.

vrna_msa_t *alignment: Set of alignments.

vrna_hc_t *hc: The hard constraints data structure used for structure prediction.

vrna_mx_mfe_t *matrices: The MFE DP matrices.

vrna_mx_pf_t *exp_matrices: The PF DP matrices

vrna_param_t *params: The precomputed free energy contributions for each type of loop.

vrna_exp_param_t *exp_params: The precomputed free energy contributions as Boltzmann factors

int *iindx: DP matrix accessor

int *jindx: DP matrix accessor

User-defined data fields

vrna_recursion_status_f stat_cb

Recursion status callback (usually called just before, and after recursive computations in the library.

void *auxdata

A pointer to auxiliary, user-defined data.

vrna_auxdata_free_f free_auxdata

A callback to free auxiliary user data whenever the fold_compound itself is free’d.

vrna_sd_t *domains_struc: Additional structured domains.

vrna_ud_t *domains_up: Additional unstructured domains.

vrna_gr_aux_t *aux_grammar: Additional decomposition grammar rules.

Data fields available for single/hybrid structure prediction

char *sequence

The input sequence string.

Warning

Only available if

type==VRNA_FC_TYPE_SINGLE

short *sequence_encoding

Numerical encoding of the input sequence.

See also

vrna_sequence_encode()

Warning

Only available if

type==VRNA_FC_TYPE_SINGLE

short *encoding5

short *encoding3

short *sequence_encoding2

char *ptype

Pair type array.

Contains the numerical encoding of the pair type for each pair (i,j) used in MFE, Partition function and Evaluation computations.

See also

vrna_idx_col_wise(), vrna_ptypes()

Note

This array is always indexed via jindx, in contrast to previously different indexing between mfe and pf variants!

Warning

Only available if

type==VRNA_FC_TYPE_SINGLE

char *ptype_pf_compat

ptype array indexed via iindx

Deprecated:: This attribute will vanish in the future! It’s meant for backward compatibility only!

Warning

Only available if

type==VRNA_FC_TYPE_SINGLE

vrna_sc_t *sc

The soft constraints for usage in structure prediction and evaluation.

Warning

Only available if

type==VRNA_FC_TYPE_SINGLE

Data fields for consensus structure prediction

char **sequences

The aligned sequences.

Note

The end of the alignment is indicated by a NULL pointer in the second dimension

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

unsigned int n_seq

The number of sequences in the alignment.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

char *cons_seq

The consensus sequence of the aligned sequences.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

short *S_cons

Numerical encoding of the consensus sequence.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

short **S

Numerical encoding of the sequences in the alignment.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

short **S5

S5[s][i] holds next base 5’ of i in sequence s.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

short **S3

Sl[s][i] holds next base 3’ of i in sequence s.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

char **Ss

unsigned int **a2s

int *pscore

Precomputed array of pair types expressed as pairing scores.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

int **pscore_local

Precomputed array of pair types expressed as pairing scores.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

short *pscore_pf_compat

Precomputed array of pair types expressed as pairing scores indexed via iindx.

Deprecated:: This attribute will vanish in the future!

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

vrna_sc_t **scs

A set of soft constraints (for each sequence in the alignment)

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE

int oldAliEn

Additional data fields for Distance Class Partitioning

These data fields are typically populated with meaningful data only if used in the context of Distance Class Partitioning

unsigned int maxD1: Maximum allowed base pair distance to first reference.

unsigned int maxD2: Maximum allowed base pair distance to second reference.

short *reference_pt1: A pairtable of the first reference structure.

short *reference_pt2: A pairtable of the second reference structure.

unsigned int *referenceBPs1: Matrix containing number of basepairs of reference structure1 in interval [i,j].

unsigned int *referenceBPs2: Matrix containing number of basepairs of reference structure2 in interval [i,j].

unsigned int *bpdist: Matrix containing base pair distance of reference structure 1 and 2 on interval [i,j].

unsigned int *mm1: Maximum matching matrix, reference struct 1 disallowed.

unsigned int *mm2: Maximum matching matrix, reference struct 2 disallowed.

Additional data fields for local folding

These data fields are typically populated with meaningful data only if used in the context of local folding

int window_size: window size for local folding sliding window approach

char **ptype_local: Pair type array (for local folding)

vrna_zsc_dat_t zscore_data: Data structure with settings for z-score computations.

Public Members

union vrna_fc_s.[anonymous] [anonymous]