RNAlib-2.2.7

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

+ Collaboration diagram for The Fold Compound:

Data Structures

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

Macros

#define VRNA_STATUS_MFE_PRE   (unsigned char)1
 Status message indicating that MFE computations are about to begin. More...
 
#define VRNA_STATUS_MFE_POST   (unsigned char)2
 Status message indicating that MFE computations are finished. More...
 
#define VRNA_STATUS_PF_PRE   (unsigned char)3
 Status message indicating that Partition function computations are about to begin. More...
 
#define VRNA_STATUS_PF_POST   (unsigned char)4
 Status message indicating that Partition function computations are finished. More...
 
#define VRNA_OPTION_MFE   1U
 Option flag to specify requirement of Minimum Free Energy (MFE) DP matrices and corresponding set of energy parameters. More...
 
#define VRNA_OPTION_PF   2U
 Option flag to specify requirement of Partition Function (PF) DP matrices and corresponding set of Boltzmann factors. More...
 
#define VRNA_OPTION_EVAL_ONLY   8U
 Option flag to specify that neither MFE, nor PF DP matrices are required. More...
 

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. More...
 
typedef void( vrna_callback_recursion_status) (unsigned char status, void *data)
 Callback to perform specific user-defined actions before, or after recursive computations. More...
 

Enumerations

enum  vrna_fc_type_e { VRNA_VC_TYPE_SINGLE, VRNA_VC_TYPE_ALIGNMENT }
 An enumerator that is used to specify the type of a vrna_fold_compound_t. More...
 

Functions

vrna_fold_compound_tvrna_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. More...
 
vrna_fold_compound_tvrna_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. More...
 
void vrna_fold_compound_free (vrna_fold_compound_t *vc)
 Free memory occupied by a vrna_fold_compound_t. More...
 
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. More...
 
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. More...
 

Detailed Description

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.


Data Structure Documentation

struct vrna_fc_s

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

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!
See also
vrna_fold_compound_t.type, vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_fold_compound_free(), VRNA_VC_TYPE_SINGLE, VRNA_VC_TYPE_ALIGNMENT
+ Collaboration diagram for vrna_fc_s:

Data Fields

Common data fields
vrna_fc_type_e type
 The type of the vrna_fold_compound_t. More...
 
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.
 
vrna_hc_thc
 The hard constraints data structure used for structure prediction.
 
vrna_mx_mfe_tmatrices
 The MFE DP matrices.
 
vrna_mx_pf_texp_matrices
 The PF DP matrices.
 
vrna_param_tparams
 The precomputed free energy contributions for each type of loop.
 
vrna_exp_param_texp_params
 The precomputed free energy contributions as Boltzmann factors.
 
int * iindx
 DP matrix accessor.
 
int * jindx
 DP matrix accessor.
 
User-defined data fields
vrna_callback_recursion_statusstat_cb
 Recursion status callback (usually called just before, and after recursive computations in the library. More...
 
void * auxdata
 A pointer to auxiliary, user-defined data. More...
 
vrna_callback_free_auxdatafree_auxdata
 A callback to free auxiliary user data whenever the fold_compound itself is free'd. More...
 
Data fields available for single/hybrid structure prediction
char * sequence
 The input sequence string. More...
 
short * sequence_encoding
 Numerical encoding of the input sequence. More...
 
short * sequence_encoding2
 
char * ptype
 Pair type array. More...
 
char * ptype_pf_compat
 ptype array indexed via iindx More...
 
vrna_sc_tsc
 The soft constraints for usage in structure prediction and evaluation. More...
 
Data fields for consensus structure prediction
char ** sequences
 The aligned sequences. More...
 
unsigned int n_seq
 The number of sequences in the alignment. More...
 
char * cons_seq
 The consensus sequence of the aligned sequences. More...
 
short * S_cons
 Numerical encoding of the consensus sequence. More...
 
short ** S
 Numerical encoding of the sequences in the alignment. More...
 
short ** S5
 S5[s][i] holds next base 5' of i in sequence s. More...
 
short ** S3
 Sl[s][i] holds next base 3' of i in sequence s. More...
 
char ** Ss
 
unsigned short ** a2s
 
int * pscore
 Precomputed array of pair types expressed as pairing scores. More...
 
short * pscore_pf_compat
 Precomputed array of pair types expressed as pairing scores indexed via iindx. More...
 
vrna_sc_t ** scs
 A set of soft constraints (for each sequence in the alignment) More...
 
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)
 

Field Documentation

vrna_fc_type_e vrna_fc_s::type

The type of the vrna_fold_compound_t.

Currently possible values are VRNA_VC_TYPE_SINGLE, and VRNA_VC_TYPE_ALIGNMENT

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.
vrna_callback_recursion_status* vrna_fc_s::stat_cb

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

See also
vrna_callback_recursion_status(), vrna_fold_compound_add_callback()
void* vrna_fc_s::auxdata

A pointer to auxiliary, user-defined data.

See also
vrna_fold_compound_add_auxdata(), vrna_fold_compound_t.free_auxdata
vrna_callback_free_auxdata* vrna_fc_s::free_auxdata

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

See also
vrna_fold_compound_t.auxdata, vrna_callback_free_auxdata()
char* vrna_fc_s::sequence

The input sequence string.

Warning
Only available if
type==VRNA_VC_TYPE_SINGLE 
short* vrna_fc_s::sequence_encoding

Numerical encoding of the input sequence.

See also
vrna_sequence_encode()
Warning
Only available if
type==VRNA_VC_TYPE_SINGLE 
char* vrna_fc_s::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.

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_VC_TYPE_SINGLE 
See also
vrna_idx_col_wise(), vrna_ptypes()
char* vrna_fc_s::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_VC_TYPE_SINGLE 
vrna_sc_t* vrna_fc_s::sc

The soft constraints for usage in structure prediction and evaluation.

Warning
Only available if
type==VRNA_VC_TYPE_SINGLE 
char** vrna_fc_s::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_VC_TYPE_ALIGNMENT 
unsigned int vrna_fc_s::n_seq

The number of sequences in the alignment.

Warning
Only available if
type==VRNA_VC_TYPE_ALIGNMENT 
char* vrna_fc_s::cons_seq

The consensus sequence of the aligned sequences.

Warning
Only available if
type==VRNA_VC_TYPE_ALIGNMENT 
short* vrna_fc_s::S_cons

Numerical encoding of the consensus sequence.

Warning
Only available if
type==VRNA_VC_TYPE_ALIGNMENT 
short** vrna_fc_s::S

Numerical encoding of the sequences in the alignment.

Warning
Only available if
type==VRNA_VC_TYPE_ALIGNMENT 
short** vrna_fc_s::S5

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

Warning
Only available if
type==VRNA_VC_TYPE_ALIGNMENT 
short** vrna_fc_s::S3

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

Warning
Only available if
type==VRNA_VC_TYPE_ALIGNMENT 
int* vrna_fc_s::pscore

Precomputed array of pair types expressed as pairing scores.

Warning
Only available if
type==VRNA_VC_TYPE_ALIGNMENT 
short* vrna_fc_s::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_VC_TYPE_ALIGNMENT 
vrna_sc_t** vrna_fc_s::scs

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

Warning
Only available if
type==VRNA_VC_TYPE_ALIGNMENT 

Macro Definition Documentation

#define VRNA_STATUS_MFE_PRE   (unsigned char)1
#define VRNA_STATUS_MFE_POST   (unsigned char)2
#define VRNA_STATUS_PF_PRE   (unsigned char)3

#include <ViennaRNA/data_structures.h>

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

See also
vrna_fold_compound_t.stat_cb, vrna_callback_recursion_status(), vrna_pf()
#define VRNA_STATUS_PF_POST   (unsigned char)4

#include <ViennaRNA/data_structures.h>

Status message indicating that Partition function computations are finished.

See also
vrna_fold_compound_t.stat_cb, vrna_callback_recursion_status(), vrna_pf()
#define VRNA_OPTION_MFE   1U

#include <ViennaRNA/data_structures.h>

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

See also
vrna_fold_compound(), vrna_fold_compound_comparative(), VRNA_OPTION_EVAL_ONLY
#define VRNA_OPTION_PF   2U

#include <ViennaRNA/data_structures.h>

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

See also
vrna_fold_compound(), vrna_fold_compound_comparative(), VRNA_OPTION_EVAL_ONLY
#define VRNA_OPTION_EVAL_ONLY   8U

#include <ViennaRNA/data_structures.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.

See also
vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_eval_structure()

Typedef Documentation

typedef void( vrna_callback_free_auxdata) (void *data)

#include <ViennaRNA/data_structures.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.

Parameters
dataThe data that needs to be free'd
typedef void( vrna_callback_recursion_status) (unsigned char status, void *data)

#include <ViennaRNA/data_structures.h>

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

See also
VRNA_STATUS_MFE_PRE, VRNA_STATUS_MFE_POST, VRNA_STATUS_PF_PRE, VRNA_STATUS_PF_POST
Parameters
statusThe status indicator
dataThe data structure that was assigned with vrna_fold_compound_add_auxdata()
statusThe status indicator

Enumeration Type Documentation

#include <ViennaRNA/data_structures.h>

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

Enumerator
VRNA_VC_TYPE_SINGLE 

Type is suitable for single, and hybridizing sequences

VRNA_VC_TYPE_ALIGNMENT 

Type is suitable for sequence alignments (consensus structure prediction)

Function Documentation

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

#include <ViennaRNA/data_structures.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. 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.

Note
The sequence string must be uppercase, and should contain only RNA (resp. DNA) alphabet depending on what energy parameter set is used
See also
vrna_fold_compound_free(), vrna_fold_compound_comparative(), vrna_md_t, VRNA_OPTION_MFE, VRNA_OPTION_PF, VRNA_OPTION_EVAL_ONLY, #VRNA_OPTION_WINDOW
Parameters
sequenceA single sequence, or two concatenated sequences seperated by an '&' character
md_pAn optional set of model details
optionsThe options for DP matrices memory allocation
Returns
A prefilled vrna_fold_compound_t that can be readily used for computations
vrna_fold_compound_t* vrna_fold_compound_comparative ( const char **  sequences,
vrna_md_t md_p,
unsigned int  options 
)

#include <ViennaRNA/data_structures.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. 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.

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.
See also
vrna_fold_compound_free(), vrna_fold_compound(), vrna_md_t, VRNA_OPTION_MFE, VRNA_OPTION_PF, VRNA_OPTION_EVAL_ONLY, read_clustal()
Parameters
sequencesA sequence alignment including 'gap' characters
md_pAn optional set of model details
optionsThe options for DP matrices memory allocation
Returns
A prefilled vrna_fold_compound_t that can be readily used for computations
void vrna_fold_compound_free ( vrna_fold_compound_t vc)

#include <ViennaRNA/data_structures.h>

Free memory occupied by a vrna_fold_compound_t.

See also
vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_mx_mfe_free(), vrna_mx_pf_free()
Parameters
vcThe 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 
)

#include <ViennaRNA/data_structures.h>

Add auxiliary data to the vrna_fold_compound_t.

This function allows 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().

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.
See also
vrna_callback_free_auxdata()
Parameters
vcThe fold_compound the arbitrary data pointer should be associated with
dataA pointer to an arbitrary data structure
fA 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 vc,
vrna_callback_recursion_status f 
)

#include <ViennaRNA/data_structures.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 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.

See also
vrna_callback_recursion_status(), vrna_fold_compound_t, VRNA_STATUS_MFE_PRE, VRNA_STATUS_MFE_POST, VRNA_STATUS_PF_PRE, VRNA_STATUS_PF_POST
Parameters
vcThe fold_compound the callback function should be attached to
fThe pointer to the recursion status callback function