Callback Functions

Table of Contents

• The purpose of Callback mechanisms
• List of available Callbacks

With the new RNAlib API v3.0 we introduce so-called callback mechanisms for several functions.

The purpose of Callback mechanisms

Using callback mechanisms, our library enables users not only to retrieve computed data without the need for parsing complicated data structures, but also allows one to tweak our implementation to do additional tasks without the requirement of a re-implementation of basic algorithms.

Our implementation of the callback mechanisms always follows the same scheme: The user:

• defines a function that complies with the interface we've defined, and
• passes a pointer to said function to our implementations

In addition to the specific arguments of our callback interfaces, virtually all callbacks receive an additional pass-through-pointer as their last argument. This enables one to:

• encapsulate data, and
• provide thread-safe operations,

since this pointer is simply passed through by our library functions. It may therefore hold the address of an arbitrary, user-defined data structure.

List of available Callbacks

Below, you find an enumeration of the individual callback functions that are available in RNAlib.

Global vrna_boltzmann_sampling_callback )(const char *stucture, void *data)

This function will be called for each secondary structure that has been successfully backtraced from the partition function DP matrices.

Global vrna_callback_free_auxdata )(void *data)

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

Global vrna_callback_hc_evaluate )(int i, int j, int k, int l, unsigned char d, void *data)

This callback enables one to over-rule default hard constraints in secondary structure decompositions.

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

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.

Global vrna_callback_sc_backtrack )(int i, int j, int k, int l, unsigned char d, void *data)

This callback enables one to add auxiliary base pairs in the backtracking steps of hairpin- and interior loops.

Global vrna_callback_sc_energy )(int i, int j, int k, int l, unsigned char d, void *data)

This callback enables one to add (pseudo-)energy contributions to individual decompositions of the secondary structure.

Global vrna_callback_sc_exp_energy )(int i, int j, int k, int l, unsigned char d, void *data)

This callback enables one to add (pseudo-)energy contributions to individual decompositions of the secondary structure (Partition function variant, i.e. contributions must be returned as Boltzmann factors).

Global vrna_callback_ud_energy )(vrna_fold_compound_t *vc, int i, int j, unsigned int loop_type, void *data)

This function will be called to determine the additional energy contribution of a specific unstructured domain, e.g. the binding free energy of some ligand.

Global vrna_callback_ud_exp_energy )(vrna_fold_compound_t *vc, int i, int j, unsigned int loop_type, void *data)

This function will be called to determine the additional energy contribution of a specific unstructured domain, e.g. the binding free energy of some ligand (Partition function variant, i.e. the Boltzmann factors instead of actual free energies).

Global vrna_callback_ud_exp_production )(vrna_fold_compound_t *vc, void *data)

The production rule for the unstructured domain grammar extension (Partition function variant)

Global vrna_callback_ud_probs_add )(vrna_fold_compound_t *vc, int i, int j, unsigned int loop_type, FLT_OR_DBL exp_energy, void *data)

A callback function to store equilibrium probabilities for the unstructured domain feature

Global vrna_callback_ud_probs_get )(vrna_fold_compound_t *vc, int i, int j, unsigned int loop_type, int motif, void *data)

A callback function to retrieve equilibrium probabilities for the unstructured domain feature

Global vrna_callback_ud_production )(vrna_fold_compound_t *vc, void *data)

The production rule for the unstructured domain grammar extension

Global vrna_mfe_window_callback )(int start, int end, const char *structure, float en, void *data)

This function will be called for each hit in a sliding window MFE prediction.

Global vrna_probs_window_callback )(FLT_OR_DBL *pr, int pr_size, int i, int max, unsigned int type, void *data)

This function will be called for each probability data set in the sliding window probability computation implementation of vrna_probs_window(). The argument type specifies the type of probability that is passed to this function.

Global vrna_subopt_callback )(const char *stucture, float energy, void *data)

This function will be called for each suboptimal secondary structure that is successfully backtraced.