Scripting Language interface(s)

Notes on functions and structures wrapped to the scripting language interface(s)

# Introduction

For an easy integration into scripting languages, we provide an automatically generated interface to the RNAlib C-library, generated with scripting.

## Function renaming scheme

The main difference when using a scripting language interface compared to direct calls of RNAlib C functions is, that the prefix 'vrna_' is dropped. For instance, when calling the vrna_fold() function, corresponding calls in perl or python are RNA::fold(), and RNA.fold(), respectively.

Functions that are dedicated to work on specific data structures only, e.g. the vrna_fold_compound_t, are usually not exported at all. Instead, they are attached as object methods of a corresponding class (see Object oriented Interface for data structures for detailed information).

## Object oriented Interface for data structures

For data structures, typedefs, and enumerations the 'vrna_' prefixes are dropped as well, together with their suffixes '_s', '_t', and '_e', respectively. Furthermore, data structures are usually transformed into classes and relevant functions of the C-library are attached as methods.

# Examples

## Perl Examples

### Using the Flat Interface

Example 1: "Simple MFE prediction"

#!/usr/bin/perl
use warnings;
use strict;
use RNA;
my $seq1 = "CGCAGGGAUACCCGCG";
# compute minimum free energy (mfe) and corresponding structure
my ($ss, $mfe) = RNA::fold($seq1);
# print output
printf "%s [ %6.2f ]\n", $ss, $mfe;

### Using the Object Oriented (OO) Interface

The 'fold_compound' class that serves as an object oriented interface for vrna_fold_compound_t

Example 1: "Simple MFE prediction"

#!/usr/bin/perl
use warnings;
use strict;
use RNA;
my $seq1 = "CGCAGGGAUACCCGCG";
# create new fold_compound object
my $fc = new RNA::fold_compound($seq1);
# compute minimum free energy (mfe) and corresponding structure
my ($ss, $mfe) = $fc->mfe();
# print output
printf "%s [ %6.2f ]\n", $ss, $mfe;

## Python Examples

# How functions, structures, enums, and macro definitions are wrapped

Global vrna_exp_params_rescale (vrna_fold_compound_t *vc, double *mfe)

  This function is attached to vrna_fc_s objects as overloaded exp_params_rescale() method.

  When no parameter is passed to this method, the resulting action is the same as passing NULL as second parameter to vrna_exp_params_rescale(), i.e. default scaling of the partition function. Passing an energy in kcal/mol, e.g. as retrieved by a previous call to the mfe() method, instructs all subsequent calls to scale the partition function accordingly.

Global vrna_exp_params_reset (vrna_fold_compound_t *vc, vrna_md_t *md_p)

  This function is attached to vrna_fc_s objects as overloaded exp_params_reset() method.

  When no parameter is passed to this method, the resulting action is the same as passing NULL as second parameter to vrna_exp_params_reset(), i.e. global default model settings are used. Passing an object of type vrna_md_s resets the fold compound according to the specifications stored within the vrna_md_s object.

Global vrna_exp_params_subst (vrna_fold_compound_t *vc, vrna_exp_param_t *params)
  This function is attached to vrna_fc_s objects as exp_params_subst() method.
Class vrna_fc_s

  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
Class vrna_md_s

  This data structure is wrapped as an object md with multiple related functions attached as methods.

  A new set of default parameters can be obtained by calling the constructure of md:

  - md() – Initialize with default settings

  The resulting object has a list of attached methods which directly correspond to functions that mainly operate on the corresponding C data structure:

  - reset() – vrna_md_set_default()
  - set_from_globals() – set_model_details()
  - option_string() – vrna_md_option_string()

  Note, that default parameters can be modified by directly setting any of the following global variables. Internally, getting/setting default parameters using their global variable representative translates into calls of the following functions, therefore these wrappers for these functions do not exist in the scripting language interface(s):

  global variable | C getter | C setter
  --- | --- | ---
  temperature | vrna_md_defaults_temperature_get() | vrna_md_defaults_temperature()
  dangles | vrna_md_defaults_dangles_get() | vrna_md_defaults_dangles()
  betaScale | vrna_md_defaults_betaScale_get() | vrna_md_defaults_betaScale()
  tetra_loop | this is an alias of special_hp |
  special_hp | vrna_md_defaults_special_hp_get() | vrna_md_defaults_special_hp()
  noLonelyPairs | this is an alias of noLP |
  noLP | vrna_md_defaults_noLP_get() | vrna_md_defaults_noLP()
  noGU | vrna_md_defaults_noGU_get() | vrna_md_defaults_noGU()
  no_closingGU | this is an alias of noGUclosure |
  noGUclosure | vrna_md_defaults_noGUclosure_get() | vrna_md_defaults_noGUclosure()
  logML | vrna_md_defaults_logML_get() | vrna_md_defaults_logML()
  circ | vrna_md_defaults_circ_get() | vrna_md_defaults_circ()
  gquad | vrna_md_defaults_gquad_get() | vrna_md_defaults_gquad()
  uniq_ML | vrna_md_defaults_uniq_ML_get() | vrna_md_defaults_uniq_ML()
  energy_set | vrna_md_defaults_energy_set_get() | vrna_md_defaults_energy_set()
  backtrack | vrna_md_defaults_backtrack_get() | vrna_md_defaults_backtrack()
  backtrack_type | vrna_md_defaults_backtrack_type_get() | vrna_md_defaults_backtrack_type()
  do_backtrack | this is an alias of compute_bpp |
  compute_bpp | vrna_md_defaults_compute_bpp_get() | vrna_md_defaults_compute_bpp()
  max_bp_span | vrna_md_defaults_max_bp_span_get() | vrna_md_defaults_max_bp_span()
  min_loop_size | vrna_md_defaults_min_loop_size_get() | vrna_md_defaults_min_loop_size()
  window_size | vrna_md_defaults_window_size_get() | vrna_md_defaults_window_size()
  oldAliEn | vrna_md_defaults_oldAliEn_get() | vrna_md_defaults_oldAliEn()
  ribo | vrna_md_defaults_ribo_get() | vrna_md_defaults_ribo()
  cv_fact | vrna_md_defaults_cv_fact_get() | vrna_md_defaults_cv_fact()
  nc_fact | vrna_md_defaults_nc_fact_get() | vrna_md_defaults_nc_fact()
  sfact | vrna_md_defaults_sfact_get() | vrna_md_defaults_sfact()

Global vrna_params_reset (vrna_fold_compound_t *vc, vrna_md_t *md_p)

  This function is attached to vrna_fc_s objects as overloaded params_reset() method.

  When no parameter is passed to this method, the resulting action is the same as passing NULL as second parameter to vrna_params_reset(), i.e. global default model settings are used. Passing an object of type vrna_md_s resets the fold compound according to the specifications stored within the vrna_md_s object.

Global vrna_params_subst (vrna_fold_compound_t *vc, vrna_param_t *par)
  This function is attached to vrna_fc_s objects as params_subst() method.