Callback Functions

Many functions in RNAlib support so-called callback mechanisms to propagate the computation results. In essence, this means that a user defines a function that takes computation results as input and does whatever should be done with these results. Then, this function is provided to our algorithms in RNAlib such that they can call the function and provide corresponding data as soon as it has been computed.

Why Callbacks?

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.

Scripting Language Support

Our callback mechanisms also work in a cross-language specific manner. This means that users can write functions (or methods) in a scripting language, such as Python, and use them as callbacks for our C-library. Our scripting language interface will take care of transforming the relevant data structures from the target language into C and vice-versa. Whenever our algorithms trigger the callback, they will then be calling the actual scripting language function and provide the corresponding data directly to them.

Warning

Keep in mind that the translation between the scripting language and C involves many extra function calls to prepare and evaluate the corresponding data structures. This in turn impacts the runtime of our algorithms that can be substantial. For instance providing callbacks for the hard- or soft constraints framework from a scripting language can lead to a slow-down of up to a factor of 10.

Available Callbacks

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

Global vrna_auxdata_free_f  )(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_bs_result_f  )(const char *structure, void *data)

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

Global vrna_hc_eval_f  )(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_heat_capacity_f  )(float temp, float heat_capacity, void *data)

This function will be called for each evaluated temperature in the heat capacity prediction.

Global vrna_mfe_window_f  )(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_f  )(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_recursion_status_f  )(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_sc_bt_f  )(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_sc_exp_f  )(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_sc_f  )(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_subopt_result_f  )(const char *stucture, float energy, void *data)

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

Global vrna_ud_add_probs_f  )(vrna_fold_compound_t *fc, 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_ud_exp_f  )(vrna_fold_compound_t *fc, 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_ud_exp_production_f  )(vrna_fold_compound_t *fc, void *data)

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

Global vrna_ud_f  )(vrna_fold_compound_t *fc, 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_ud_get_probs_f  )(vrna_fold_compound_t *fc, 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_ud_production_f  )(vrna_fold_compound_t *fc, void *data)

The production rule for the unstructured domain grammar extension