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

Collaboration diagram for The Fold Compound:

Files
file	fold_compound.h
	The Basic Fold Compound API.

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_DEFAULT   0U
	Option flag to specify default settings/requirements.
#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_HYBRID   4U
	Option flag to specify requirement of dimer DP matrices.
#define	VRNA_OPTION_EVAL_ONLY   8U
	Option flag to specify that neither MFE, nor PF DP matrices are required. More...
#define	VRNA_OPTION_WINDOW   16U
	Option flag to specify requirement of DP matrices for local folding approaches.

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

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. More...
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. More...
void	vrna_fold_compound_free (vrna_fold_compound_t *fc)
	Free memory occupied by a vrna_fold_compound_t. More...
void	vrna_fold_compound_add_auxdata (vrna_fold_compound_t *fc, 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 *fc, vrna_callback_recursion_status *f)
	Add a recursion status callback to the vrna_fold_compound_t. More...

---

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_FC_TYPE_SINGLE, VRNA_FC_TYPE_COMPARATIVE

SWIG Wrapper Notes:

This data structure is wrapped as an object 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

Collaboration diagram for vrna_fc_s:

Data Fields
Common data fields
const 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.
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_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
vrna_seq_t *	nucleotides
vrna_msa_t *	alignment
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_callback_recursion_status *	stat_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_auxdata *	free_auxdata
	A callback to free auxiliary user data whenever the fold_compound itself is free'd. More...
Secondary Structure Decomposition (grammar) related data fields
vrna_sd_t *	domains_struc
	Additional structured domains.
vrna_ud_t *	domains_up
	Additional unstructured domains.
vrna_gr_aux_t *	aux_grammar
Data fields available for single/hybrid structure prediction
Data fields for consensus structure prediction
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

const vrna_fc_type_e vrna_fc_s::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.

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_FC_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_FC_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_FC_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_FC_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_FC_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_FC_TYPE_COMPARATIVE 

unsigned int vrna_fc_s::n_seq

The number of sequences in the alignment.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE 

char* vrna_fc_s::cons_seq

The consensus sequence of the aligned sequences.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE 

short* vrna_fc_s::S_cons

Numerical encoding of the consensus sequence.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE 

short** vrna_fc_s::S

Numerical encoding of the sequences in the alignment.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE 

short** vrna_fc_s::S5

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

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE 

short** vrna_fc_s::S3

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

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE 

int* vrna_fc_s::pscore

Precomputed array of pair types expressed as pairing scores.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE 

int** vrna_fc_s::pscore_local

Precomputed array of pair types expressed as pairing scores.

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE 

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_FC_TYPE_COMPARATIVE 

vrna_sc_t** vrna_fc_s::scs

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

Warning

Only available if

type==VRNA_FC_TYPE_COMPARATIVE 

Macro Definition Documentation

#define VRNA_STATUS_MFE_PRE   (unsigned char)1

#include <ViennaRNA/fold_compound.h>

Status message indicating that MFE computations are about to begin.

See also

vrna_fold_compound_t.stat_cb, vrna_callback_recursion_status(), vrna_mfe(), vrna_fold(), vrna_circfold(), vrna_alifold(), vrna_circalifold(), vrna_cofold()

#define VRNA_STATUS_MFE_POST   (unsigned char)2

#include <ViennaRNA/fold_compound.h>

Status message indicating that MFE computations are finished.

See also

vrna_fold_compound_t.stat_cb, vrna_callback_recursion_status(), vrna_mfe(), vrna_fold(), vrna_circfold(), vrna_alifold(), vrna_circalifold(), vrna_cofold()

#define VRNA_STATUS_PF_PRE   (unsigned char)3

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

See also

vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_eval_structure()

Typedef Documentation

typedef void( vrna_callback_free_auxdata) (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().

See also

vrna_fold_compound_add_auxdata(), vrna_fold_compound_free(), vrna_fold_compound_add_callback()

Parameters

data	The data that needs to be free'd

typedef void( vrna_callback_recursion_status) (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.

See also

vrna_fold_compound_add_auxdata(), vrna_fold_compound_add_callback(), vrna_mfe(), vrna_pf(), VRNA_STATUS_MFE_PRE, VRNA_STATUS_MFE_POST, VRNA_STATUS_PF_PRE, VRNA_STATUS_PF_POST

Parameters

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

Enumeration Type Documentation

enum vrna_fc_type_e

#include <ViennaRNA/fold_compound.h>

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

Enumerator
VRNA_FC_TYPE_SINGLE	Type is suitable for single, and hybridizing sequences
VRNA_FC_TYPE_COMPARATIVE	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/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

See also

vrna_fold_compound_free(), vrna_fold_compound_comparative(), vrna_md_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 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.

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

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)

void vrna_fold_compound_free

(

vrna_fold_compound_t *

fc

)

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

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

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_callback_recursion_status *	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.

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

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