Fine-tuning of the implemented models

Overview

Functions and data structures to fine-tune the implemented secondary structure evaluation model. More…

// typedefs

typedef struct vrna_md_s vrna_md_t

// structs

struct vrna_md_s

// global variables

double temperature
double pf_scale
int dangles
int tetra_loop
int noLonelyPairs
int noGU
int no_closingGU
int circ
int gquad
int uniq_ML
int energy_set
int do_backtrack
char backtrack_type
char* nonstandards
int max_bp_span
int oldAliEn
int ribo
double cv_fact
double nc_fact
int logML

// global functions

void vrna_md_set_default (vrna_md_t* md)
void vrna_md_update (vrna_md_t* md)

vrna_md_t* vrna_md_copy (
    vrna_md_t* md_to,
    const vrna_md_t* md_from
    )

char* vrna_md_option_string (vrna_md_t* md)

void vrna_md_set_nonstandards (
    vrna_md_t* md,
    const char* ns_bases
    )

void vrna_md_defaults_reset (vrna_md_t* md_p)
void vrna_md_defaults_temperature (double T)
double vrna_md_defaults_temperature_get (void)
void vrna_md_defaults_betaScale (double b)
double vrna_md_defaults_betaScale_get (void)
void vrna_md_defaults_dangles (int d)
int vrna_md_defaults_dangles_get (void)
void vrna_md_defaults_special_hp (int flag)
int vrna_md_defaults_special_hp_get (void)
void vrna_md_defaults_noLP (int flag)
int vrna_md_defaults_noLP_get (void)
void vrna_md_defaults_noGU (int flag)
int vrna_md_defaults_noGU_get (void)
void vrna_md_defaults_noGUclosure (int flag)
int vrna_md_defaults_noGUclosure_get (void)
void vrna_md_defaults_logML (int flag)
int vrna_md_defaults_logML_get (void)
void vrna_md_defaults_circ (int flag)
int vrna_md_defaults_circ_get (void)
void vrna_md_defaults_gquad (int flag)
int vrna_md_defaults_gquad_get (void)
void vrna_md_defaults_uniq_ML (int flag)
int vrna_md_defaults_uniq_ML_get (void)
void vrna_md_defaults_energy_set (int e)
int vrna_md_defaults_energy_set_get (void)
void vrna_md_defaults_backtrack (int flag)
int vrna_md_defaults_backtrack_get (void)
void vrna_md_defaults_backtrack_type (char t)
char vrna_md_defaults_backtrack_type_get (void)
void vrna_md_defaults_compute_bpp (int flag)
int vrna_md_defaults_compute_bpp_get (void)
void vrna_md_defaults_max_bp_span (int span)
int vrna_md_defaults_max_bp_span_get (void)
void vrna_md_defaults_min_loop_size (int size)
int vrna_md_defaults_min_loop_size_get (void)
void vrna_md_defaults_window_size (int size)
int vrna_md_defaults_window_size_get (void)
void vrna_md_defaults_oldAliEn (int flag)
int vrna_md_defaults_oldAliEn_get (void)
void vrna_md_defaults_ribo (int flag)
int vrna_md_defaults_ribo_get (void)
void vrna_md_defaults_cv_fact (double factor)
double vrna_md_defaults_cv_fact_get (void)
void vrna_md_defaults_nc_fact (double factor)
double vrna_md_defaults_nc_fact_get (void)
void vrna_md_defaults_sfact (double factor)
double vrna_md_defaults_sfact_get (void)
void set_model_details (vrna_md_t* md)
char* option_string (void)

// macros

#define MAXALPHA
#define NBASES
#define VRNA_MODEL_DEFAULT_ALI_CV_FACT
#define VRNA_MODEL_DEFAULT_ALI_NC_FACT
#define VRNA_MODEL_DEFAULT_ALI_OLD_EN
#define VRNA_MODEL_DEFAULT_ALI_RIBO
#define VRNA_MODEL_DEFAULT_BACKTRACK
#define VRNA_MODEL_DEFAULT_BACKTRACK_TYPE
#define VRNA_MODEL_DEFAULT_BETA_SCALE
#define VRNA_MODEL_DEFAULT_CIRC
#define VRNA_MODEL_DEFAULT_COMPUTE_BPP
#define VRNA_MODEL_DEFAULT_DANGLES
#define VRNA_MODEL_DEFAULT_ENERGY_SET
#define VRNA_MODEL_DEFAULT_GQUAD
#define VRNA_MODEL_DEFAULT_LOG_ML
#define VRNA_MODEL_DEFAULT_MAX_BP_SPAN
#define VRNA_MODEL_DEFAULT_NO_GU
#define VRNA_MODEL_DEFAULT_NO_GU_CLOSURE
#define VRNA_MODEL_DEFAULT_NO_LP
#define VRNA_MODEL_DEFAULT_PF_SCALE
#define VRNA_MODEL_DEFAULT_SPECIAL_HP
#define VRNA_MODEL_DEFAULT_TEMPERATURE
#define VRNA_MODEL_DEFAULT_UNIQ_ML
#define VRNA_MODEL_DEFAULT_WINDOW_SIZE
#define model_detailsT

Detailed Documentation

Functions and data structures to fine-tune the implemented secondary structure evaluation model.

Typedefs

typedef struct vrna_md_s vrna_md_t
Typename for the model details data structure vrna_md_s .

Global Variables

double temperature
Rescale energy parameters to a temperature in degC.

Default is 37C. You have to call the update_…_params() functions after changing this parameter. Deprecated Use vrna_md_defaults_temperature() , and vrna_md_defaults_temperature_get() to change, and read the global default temperature settings

double pf_scale
A scaling factor used by pf_fold() to avoid overflows.

Should be set to approximately \(exp{((-F/kT)/length)}\) , where \(F\) is an estimate for the ensemble free energy, for example the minimum free energy. You must call update_pf_params() after changing this parameter.

If pf_scale is -1 (the default) , an estimate will be provided automatically when computing partition functions, e.g. pf_fold() The automatic estimate is usually insufficient for sequences more than a few hundred bases long.

int dangles
Switch the energy model for dangling end contributions (0, 1, 2, 3)

If set to 0 no stabilizing energies are assigned to bases adjacent to helices in free ends and multiloops (so called dangling ends). Normally (dangles = 1) dangling end energies are assigned only to unpaired bases and a base cannot participate simultaneously in two dangling ends. In the partition function algorithm pf_fold() these checks are neglected. If dangles is set to 2, all folding routines will follow this convention. This treatment of dangling ends gives more favorable energies to helices directly adjacent to one another, which can be beneficial since such helices often do engage in stabilizing interactions through co-axial stacking.

If dangles = 3 co-axial stacking is explicitly included for adjacent helices in multiloops. The option affects only mfe folding and energy evaluation ( fold() and energy_of_structure() ), as well as suboptimal folding ( subopt() ) via re-evaluation of energies. Co-axial stacking with one intervening mismatch is not considered so far.

Default is 2 in most algorithms, partition function algorithms can only handle 0 and 2

int tetra_loop
Include special stabilizing energies for some tri-, tetra- and hexa-loops;.
default is 1.
int noLonelyPairs
Global switch to avoid/allow helices of length 1.
Disallow all pairs which can only occur as lonely pairs (i.e. as helix of length 1). This avoids lonely base pairs in the predicted structures in most cases.
int noGU
Global switch to forbid/allow GU base pairs at all.
int no_closingGU
GU allowed only inside stacks if set to 1.
int circ
backward compatibility variable.. this does not effect anything
int gquad
Allow G-quadruplex formation.
int uniq_ML
do ML decomposition uniquely (for subopt)
int energy_set
0 = BP; 1=any with GC; 2=any with AU-parameter
If set to 1 or 2: fold sequences from an artificial alphabet ABCD…, where A pairs B, C pairs D, etc. using either GC (1) or AU parameters (2); default is 0, you probably don’t want to change it.
int do_backtrack
do backtracking, i.e. compute secondary structures or base pair probabilities
If 0, do not calculate pair probabilities in pf_fold() ; this is about twice as fast. Default is 1.
char backtrack_type
A backtrack array marker for inverse_fold()
If set to ‘C’: force (1,N) to be paired, ‘M’ fold as if the sequence were inside a multiloop. Otherwise (‘F’) the usual mfe structure is computed.
char* nonstandards
contains allowed non standard base pairs
Lists additional base pairs that will be allowed to form in addition to GC, CG, AU, UA, GU and UG. Nonstandard base pairs are given a stacking energy of 0.
int max_bp_span
Maximum allowed base pair span.
A value of -1 indicates no restriction for distant base pairs.
int oldAliEn
use old alifold energies (with gaps)
int ribo
use ribosum matrices
int logML
if nonzero use logarithmic ML energy in energy_of_struct

Global Functions

void vrna_md_set_default (vrna_md_t* md)
Apply default model details to a provided vrna_md_t data structure.

Use this function to initialize a vrna_md_t data structure with its default values

Parameters:

md A pointer to the data structure that is about to be initialized
void vrna_md_update (vrna_md_t* md)
Update the model details data structure.

This function should be called after changing the vrna_md_t.energy_set attribute since it re-initializes base pairing related arrays within the vrna_md_t data structure. In particular, vrna_md_t.pair , vrna_md_t.alias , and vrna_md_t.rtype are set to the values that correspond to the specified vrna_md_t.energy_set option

vrna_md_t* vrna_md_copy (
    vrna_md_t* md_to,
    const vrna_md_t* md_from
    )
Copy/Clone a vrna_md_t model.

Use this function to clone a given model either inplace (target container md_to given) or create a copy by cloning the source model and returning it ( md_to == NULL).

Parameters:

md_to The model to be overwritten (if non-NULL and md_to != md_from )
md_from The model to copy (if non-NULL)

Returns:

A pointer to the copy model (or NULL if md_from == NULL)

char* vrna_md_option_string (vrna_md_t* md)
Get a corresponding commandline parameter string of the options in a vrna_md_t .

Note

This function is not threadsafe!

void vrna_md_defaults_reset (vrna_md_t* md_p)
Reset the global default model details to a specific set of parameters, or their initial values.

This function resets the global default model details to their initial values, i.e. as specified by the ViennaRNA Package release, upon passing NULL as argument. Alternatively it resets them according to a set of provided parameters.

Parameters:

md_p A set of model details to use as global default (if NULL is passed, factory defaults are restored)

Note

The global default parameters affect all function calls of RNAlib where model details are not explicitly provided. Hence, any change of them is not considered threadsafe

Warning

This function first resets the global default settings to factory defaults, and only then applies user provided settings (if any). User settings that do not meet specifications are skipped.

void vrna_md_defaults_temperature (double T)
Set default temperature for energy evaluation of loops.

Parameters:

T Temperature in centigrade
double vrna_md_defaults_temperature_get (void)
Get default temperature for energy evaluation of loops.

Returns:

The global default settings for temperature in centigrade

void vrna_md_defaults_betaScale (double b)
Set default scaling factor of thermodynamic temperature in Boltzmann factors.

Bolzmann factors are then computed as :math:` exp(-E / (b cdot kT))` .

Parameters:

b The scaling factor, default is 1.0
double vrna_md_defaults_betaScale_get (void)
Get default scaling factor of thermodynamic temperature in Boltzmann factors.

Returns:

The global default thermodynamic temperature scaling factor

void vrna_md_defaults_dangles (int d)
Set default dangle model for structure prediction.
int vrna_md_defaults_dangles_get (void)
Get default dangle model for structure prediction.

Returns:

The global default settings for the dangle model

void vrna_md_defaults_special_hp (int flag)
Set default behavior for lookup of tabulated free energies for special hairpin loops, such as Tri-, Tetra-, or Hexa-loops.

Parameters:

flag On/Off switch (0 = OFF, else = ON)
int vrna_md_defaults_special_hp_get (void)
Get default behavior for lookup of tabulated free energies for special hairpin loops, such as Tri-, Tetra-, or Hexa-loops.

Returns:

The global default settings for the treatment of special hairpin loops

void vrna_md_defaults_noLP (int flag)
Set default behavior for prediction of canonical secondary structures.

Parameters:

flag On/Off switch (0 = OFF, else = ON)
int vrna_md_defaults_noLP_get (void)
Get default behavior for prediction of canonical secondary structures.

Returns:

The global default settings for predicting canonical secondary structures

void vrna_md_defaults_noGU (int flag)
Set default behavior for treatment of G-U wobble pairs.

Parameters:

flag On/Off switch (0 = OFF, else = ON)
int vrna_md_defaults_noGU_get (void)
Get default behavior for treatment of G-U wobble pairs.

Returns:

The global default settings for treatment of G-U wobble pairs

void vrna_md_defaults_noGUclosure (int flag)
Set default behavior for G-U pairs as closing pair for loops.

Parameters:

flag On/Off switch (0 = OFF, else = ON)
int vrna_md_defaults_noGUclosure_get (void)
Get default behavior for G-U pairs as closing pair for loops.

Returns:

The global default settings for treatment of G-U pairs closing a loop

void vrna_md_defaults_logML (int flag)
Set default behavior recomputing free energies of multi-branch loops using a logarithmic model.

Parameters:

flag On/Off switch (0 = OFF, else = ON)
int vrna_md_defaults_logML_get (void)
Get default behavior recomputing free energies of multi-branch loops using a logarithmic model.

Returns:

The global default settings for logarithmic model in multi-branch loop free energy evaluation

void vrna_md_defaults_circ (int flag)
Set default behavior whether input sequences are circularized.

Parameters:

flag On/Off switch (0 = OFF, else = ON)
int vrna_md_defaults_circ_get (void)
Get default behavior whether input sequences are circularized.

Returns:

The global default settings for treating input sequences as circular

void vrna_md_defaults_gquad (int flag)
Set default behavior for treatment of G-Quadruplexes.

Parameters:

flag On/Off switch (0 = OFF, else = ON)
int vrna_md_defaults_gquad_get (void)
Get default behavior for treatment of G-Quadruplexes.

Returns:

The global default settings for treatment of G-Quadruplexes

void vrna_md_defaults_uniq_ML (int flag)
Set default behavior for creating additional matrix for unique multi-branch loop prediction.

Parameters:

flag On/Off switch (0 = OFF, else = ON)

Note

Activating this option usually results in higher memory consumption!

int vrna_md_defaults_uniq_ML_get (void)
Get default behavior for creating additional matrix for unique multi-branch loop prediction.

Returns:

The global default settings for creating additional matrices for unique multi-branch loop prediction

void vrna_md_defaults_energy_set (int e)
Set default energy set.

Parameters:

e Energy set (0, 1, 2, 3)
int vrna_md_defaults_energy_set_get (void)
Get default energy set.

Returns:

The global default settings for the energy set

void vrna_md_defaults_backtrack (int flag)
Set default behavior for whether to backtrack secondary structures.

Parameters:

flag On/Off switch (0 = OFF, else = ON)
int vrna_md_defaults_backtrack_get (void)
Get default behavior for whether to backtrack secondary structures.

Returns:

The global default settings for backtracking structures

void vrna_md_defaults_backtrack_type (char t)
Set default backtrack type, i.e. which DP matrix is used.

Parameters:

t The type (‘F’, ‘C’, or ‘M’)
char vrna_md_defaults_backtrack_type_get (void)
Get default backtrack type, i.e. which DP matrix is used.

Returns:

The global default settings that specify which DP matrix is used for backtracking

void vrna_md_defaults_compute_bpp (int flag)
Set the default behavior for whether to compute base pair probabilities after partition function computation.

Parameters:

flag On/Off switch (0 = OFF, else = ON)
int vrna_md_defaults_compute_bpp_get (void)
Get the default behavior for whether to compute base pair probabilities after partition function computation.

Returns:

The global default settings that specify whether base pair probabilities are computed together with partition function

void vrna_md_defaults_max_bp_span (int span)
Set default maximal base pair span.

Parameters:

span Maximal base pair span
int vrna_md_defaults_max_bp_span_get (void)
Get default maximal base pair span.

Returns:

The global default settings for maximum base pair span

void vrna_md_defaults_min_loop_size (int size)
Set default minimal loop size.

Parameters:

size Minimal size, i.e. number of unpaired nucleotides for a hairpin loop
int vrna_md_defaults_min_loop_size_get (void)
Get default minimal loop size.

Returns:

The global default settings for minimal size of hairpin loops

void vrna_md_defaults_window_size (int size)
Set default window size for sliding window structure prediction approaches.

Parameters:

size The size of the sliding window
int vrna_md_defaults_window_size_get (void)
Get default window size for sliding window structure prediction approaches.

Returns:

The global default settings for the size of the sliding window

void vrna_md_defaults_oldAliEn (int flag)
Set default behavior for whether to use old energy model for comparative structure prediction.

Parameters:

flag On/Off switch (0 = OFF, else = ON)

Note

This option is outdated. Activating the old energy model usually results in worse consensus structure predictions.

int vrna_md_defaults_oldAliEn_get (void)
Get default behavior for whether to use old energy model for comparative structure prediction.

Returns:

The global default settings for using old energy model for comparative structure prediction

void vrna_md_defaults_ribo (int flag)
Set default behavior for whether to use Ribosum Scoring in comparative structure prediction.

Parameters:

flag On/Off switch (0 = OFF, else = ON)
int vrna_md_defaults_ribo_get (void)
Get default behavior for whether to use Ribosum Scoring in comparative structure prediction.

Returns:

The global default settings for using Ribosum scoring in comparative structure prediction

void vrna_md_defaults_cv_fact (double factor)
Set the default co-variance scaling factor used in comparative structure prediction.

Parameters:

factor The co-variance factor
double vrna_md_defaults_cv_fact_get (void)
Get the default co-variance scaling factor used in comparative structure prediction.

Returns:

The global default settings for the co-variance factor

void vrna_md_defaults_nc_fact (double factor)
double vrna_md_defaults_nc_fact_get (void)
void vrna_md_defaults_sfact (double factor)
Set the default scaling factor used to avoid under-/overflows in partition function computation.

Parameters:

factor The scaling factor (default: 1.07)
double vrna_md_defaults_sfact_get (void)
Get the default scaling factor used to avoid under-/overflows in partition function computation.

Returns:

The global default settings of the scaling factor

void set_model_details (vrna_md_t* md)
Set default model details.

Use this function if you wish to initialize a vrna_md_t data structure with its default values, i.e. the global model settings as provided by the deprecated global variables.

Deprecated This function will vanish as soon as backward compatibility of RNAlib is dropped (expected in version 3). Use vrna_md_set_default() instead!

Parameters:

md A pointer to the data structure that is about to be initialized

Macros

#define MAXALPHA
Maximal length of alphabet.
#define VRNA_MODEL_DEFAULT_ALI_CV_FACT
Default model behavior for weighting the co-variance score in consensus structure prediction.
#define VRNA_MODEL_DEFAULT_ALI_NC_FACT
Default model behavior for weighting the nucleotide conservation? in consensus structure prediction.
#define VRNA_MODEL_DEFAULT_ALI_OLD_EN
Default model behavior for consensus structure energy evaluation.
#define VRNA_MODEL_DEFAULT_ALI_RIBO
Default model behavior for consensus structure co-variance contribution assessment.
#define VRNA_MODEL_DEFAULT_BACKTRACK
Default model behavior with regards to backtracking of structures.
#define VRNA_MODEL_DEFAULT_BACKTRACK_TYPE
Default model behavior on what type of backtracking to perform.
#define VRNA_MODEL_DEFAULT_BETA_SCALE
Default scaling factor for absolute thermodynamic temperature in Boltzmann factors.
#define VRNA_MODEL_DEFAULT_CIRC
Default model behavior to treat a molecule as a circular RNA (DNA)
#define VRNA_MODEL_DEFAULT_COMPUTE_BPP
Default model behavior with regards to computing base pair probabilities.
#define VRNA_MODEL_DEFAULT_DANGLES
Default dangling end model.
#define VRNA_MODEL_DEFAULT_ENERGY_SET
Default model behavior on which energy set to use.
#define VRNA_MODEL_DEFAULT_GQUAD
Default model behavior regarding the treatment of G-Quadruplexes.
#define VRNA_MODEL_DEFAULT_LOG_ML
Default model behavior on how to evaluate the energy contribution of multi-branch loops.
#define VRNA_MODEL_DEFAULT_MAX_BP_SPAN
Default model behavior for the allowed maximum base pair span.
#define VRNA_MODEL_DEFAULT_NO_GU
Default model behavior for G-U base pairs.
#define VRNA_MODEL_DEFAULT_NO_GU_CLOSURE
Default model behavior for G-U base pairs closing a loop.
#define VRNA_MODEL_DEFAULT_NO_LP
Default model behavior for so-called ‘lonely pairs’.
#define VRNA_MODEL_DEFAULT_PF_SCALE
Default scaling factor for partition function computations.
#define VRNA_MODEL_DEFAULT_SPECIAL_HP
Default model behavior for lookup of special tri-, tetra-, and hexa-loops.
#define VRNA_MODEL_DEFAULT_TEMPERATURE
#define VRNA_MODEL_DEFAULT_UNIQ_ML
Default behavior of the model regarding unique multi-branch loop decomposition.
#define VRNA_MODEL_DEFAULT_WINDOW_SIZE
Default model behavior for the sliding window approach.