The Fold Compound

Overview

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

// typedefs

typedef struct vrna_fc_s vrna_fold_compound_t
typedef void () vrna_callback_free_auxdata (void *data)

typedef void () vrna_callback_recursion_status (
    unsigned char status,
    void *data
    )

// enums

enum vrna_fc_type_e

// structs

struct vrna_fc_s

// global functions

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

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

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
    )

int vrna_fold_compound_prepare (
    vrna_fold_compound_t* vc,
    unsigned int options
    )

void vrna_fold_compound_free (vrna_fold_compound_t* vc)

void vrna_fold_compound_add_auxdata (
    vrna_fold_compound_t* vc,
    void* data,
    vrna_callback_free_auxdata* f
    )

void vrna_fold_compound_add_callback (
    vrna_fold_compound_t* vc,
    vrna_callback_recursion_status* f
    )

// macros

#define VRNA_OPTION_DEFAULT
#define VRNA_OPTION_EVAL_ONLY
#define VRNA_OPTION_HYBRID
#define VRNA_OPTION_MFE
#define VRNA_OPTION_PF
#define VRNA_OPTION_WINDOW
#define VRNA_STATUS_MFE_POST
#define VRNA_STATUS_MFE_PRE
#define VRNA_STATUS_PF_POST
#define VRNA_STATUS_PF_PRE

Detailed Documentation

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.

Typedefs

typedef struct vrna_fc_s vrna_fold_compound_t
Typename for the fold_compound data structure vrna_fc_s .
typedef void () vrna_callback_free_auxdata (void *data)
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() .

Parameters:

data The data that needs to be free’d
typedef void () vrna_callback_recursion_status (
    unsigned char status,
    void *data
    )
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.

Parameters:

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

Global Functions

vrna_fold_compound_t* vrna_fold_compound (
    const char* sequence,
    vrna_md_t* md_p,
    unsigned int options
    )
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. Use the macros:

to specify the required type of computations that will be performed with the vrna_fold_compound_t .

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 .

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 that can be readily used for computations

Note

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

vrna_fold_compound_t* vrna_fold_compound_comparative (
    const char** sequences,
    vrna_md_t* md_p,
    unsigned int options
    )
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. Use the macros:

to specify the required type of computations that will be performed with the vrna_fold_compound_t .

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 .

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 that can be readily used for computations

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.

void vrna_fold_compound_free (vrna_fold_compound_t* vc)
Free memory occupied by a vrna_fold_compound_t .

Parameters:

vc The vrna_fold_compound_t that is to be erased from memory
void vrna_fold_compound_add_auxdata (
    vrna_fold_compound_t* vc,
    void* data,
    vrna_callback_free_auxdata* f
    )
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_callback_recursion_status() . 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() .

Parameters:

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

Note

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

void vrna_fold_compound_add_callback (
    vrna_fold_compound_t* vc,
    vrna_callback_recursion_status* f
    )
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:

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

Macros

#define VRNA_OPTION_DEFAULT
Option flag to specify default settings/requirements.
#define VRNA_OPTION_EVAL_ONLY
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.

#define VRNA_OPTION_HYBRID
Option flag to specify requirement of dimer DP matrices.
#define VRNA_OPTION_MFE
Option flag to specify requirement of Minimum Free Energy (MFE) DP matrices and corresponding set of energy parameters.
#define VRNA_OPTION_PF
Option flag to specify requirement of Partition Function (PF) DP matrices and corresponding set of Boltzmann factors.
#define VRNA_OPTION_WINDOW
Option flag to specify requirement of DP matrices for local folding approaches.
#define VRNA_STATUS_MFE_POST
Status message indicating that MFE computations are finished.
#define VRNA_STATUS_MFE_PRE
Status message indicating that MFE computations are about to begin.
#define VRNA_STATUS_PF_POST
Status message indicating that Partition function computations are finished.
#define VRNA_STATUS_PF_PRE
Status message indicating that Partition function computations are about to begin.