The Fold Compound
Data Structures and Preprocessor Macros

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_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 *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:
[legend]

### 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_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...
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_t * | sc
| 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

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

  data | The 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

  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/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:

- VRNA_OPTION_MFE
- VRNA_OPTION_PF
- #VRNA_OPTION_WINDOW
- VRNA_OPTION_EVAL_ONLY
- #VRNA_OPTION_DEFAULT

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

  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

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:

- VRNA_OPTION_MFE
- VRNA_OPTION_PF
- VRNA_OPTION_EVAL_ONLY
- #VRNA_OPTION_DEFAULT

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

  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

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

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

`#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

  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)

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

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