RNAlib API v3.0

# Introduction

With version 2.2 we introduce the new API that will take over the old one in the future version 3.0. By then, backwards compatibility will be broken, and third party applications using RNAlib need to be ported. This switch of API became necessary, since many new features found their way into the RNAlib where a balance between threadsafety and easy-to-use library functions is hard or even impossible to establish. Furthermore, many old functions of the library are present as slightly modified copies of themself to provide a crude way to overload functions.

Therefore, we introduce the new v3.0 API very early in our development stage such that developers have enough time to migrate to the new functions and interfaces. We also started to provide encapsulation of the RNAlib functions, data structures, typedefs, and macros by prefixing them with vrna_ and VRNA_ , respectively. Header files should also be included using the ViennaRNA/ namespace, e.g.

#include <ViennaRNA/fold.h>

instead of just using

#include <fold.h>

as required for RNAlib 1.x and 2.x.

This eases the work for programmers of third party applications that would otherwise need to put much effort into renaming functions and data types in their own implementations if their names appear in our library. Since we still provide backward compatibility up to the last version of RNAlib 2.x, this advantage may be fully exploited only starting from v3.0 which will be released in the future. However, our plan is to provide the possibility for an early switch-off mechanism of the backward compatibility in one of our next releases of ViennaRNA Package 2.x.

# What are the major changes?

...

# How to port your program to the new API

...

# Some Examples using RNAlib API v3.0

Below are some example programs and code fragments that show the usage of the new API that is introduced with ViennaRNA version 2.2.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ViennaRNA/data_structures.h>
#include <ViennaRNA/params.h>
#include <ViennaRNA/utils.h>
#include <ViennaRNA/eval.h>
#include <ViennaRNA/fold.h>
#include <ViennaRNA/part_func.h>
int main(int argc, char *argv[]){
char *seq = "AGACGACAAGGUUGAAUCGCACCCACAGUCUAUGAGUCGGUGACAACAUUACGAAAGGCUGUAAAAUCAAUUAUUCACCACAGGGGGCCCCCGUGUCUAG";
char *mfe_structure = vrna_alloc(sizeof(char) * (strlen(seq) + 1));
char *prob_string = vrna_alloc(sizeof(char) * (strlen(seq) + 1));
/* get a vrna_fold_compound with MFE and PF DP matrices and default model details */
vrna_fold_compound_t *vc = vrna_fold_compound(seq, NULL, VRNA_OPTION_MFE | VRNA_OPTION_PF);
/* call MFE function */
double mfe = (double)vrna_mfe(vc, mfe_structure);
printf("%s\n%s (%6.2f)\n", seq, mfe_structure, mfe);
/* rescale parameters for Boltzmann factors */
vrna_exp_params_rescale(vc, &mfe);
/* call PF function */
FLT_OR_DBL en = vrna_pf(vc, prob_string);
/* print probability string and free energy of ensemble */
printf("%s (%6.2f)\n", prob_string, en);
/* compute centroid structure */
double dist;
char *cent = vrna_centroid(vc, &dist);
/* print centroid structure, its free energy and mean distance to the ensemble */
printf("%s (%6.2f d=%6.2f)\n", cent, vrna_eval_structure(vc, cent), dist);
/* free centroid structure */
free(cent);
/* free pseudo dot-bracket probability string */
free(prob_string);
/* free mfe structure */
free(mfe_structure);
/* free memory occupied by vrna_fold_compound */
vrna_fold_compound_free(vc);
return EXIT_SUCCESS;
}