Energy Parameter Sets and Boltzmann Factors

All relevant functions to retrieve and copy precalculated energy parameter sets as well as reading/writing the energy parameter set from/to file(s). More...

Collaboration diagram for Energy Parameter Sets and Boltzmann Factors:

## Modules

| Reading/Writing Energy Parameter Sets from/to File
| Read and Write energy parameter sets from and to text files.

## Files

file | params.h

## Data Structures

struct | vrna_param_s
| The datastructure that contains temperature scaled energy parameters. More...
struct | vrna_exp_param_s
| The datastructure that contains temperature scaled Boltzmann weights of the energy parameters. More...

## Typedefs

typedef struct vrna_param_s | vrna_param_t
| Typename for the free energy parameter data structure vrna_params.
typedef struct vrna_exp_param_s | vrna_exp_param_t
| Typename for the Boltzmann factor data structure vrna_exp_params.
typedef struct vrna_param_s | paramT
| Old typename of vrna_param_s. More...
typedef struct vrna_exp_param_s | pf_paramT
| Old typename of #vrna_ex_param_s. More...

## Functions

vrna_param_t * | vrna_params (vrna_md_t *md)
| Get a data structure containing prescaled free energy parameters. More...
vrna_param_t * | vrna_params_copy (vrna_param_t *par)
| Get a copy of the provided free energy parameters. More...
vrna_exp_param_t * | vrna_exp_params (vrna_md_t *md)
| Get a data structure containing prescaled free energy parameters already transformed to Boltzmann factors. More...
vrna_exp_param_t * | vrna_exp_params_comparative (unsigned int n_seq, vrna_md_t *md)
| Get a data structure containing prescaled free energy parameters already transformed to Boltzmann factors (alifold version) More...
vrna_exp_param_t * | vrna_exp_params_copy (vrna_exp_param_t *par)
| Get a copy of the provided free energy parameters (provided as Boltzmann factors) More...
void | vrna_params_subst (vrna_fold_compound_t *vc, vrna_param_t *par)
| Update/Reset energy parameters data structure within a vrna_fold_compound_t. More...
void | vrna_exp_params_subst (vrna_fold_compound_t *vc, vrna_exp_param_t *params)
| Update the energy parameters for subsequent partition function computations. More...
void | vrna_exp_params_rescale (vrna_fold_compound_t *vc, double *mfe)
| Rescale Boltzmann factors for partition function computations. More...
void | vrna_params_reset (vrna_fold_compound_t *vc, vrna_md_t *md_p)
| Reset free energy parameters within a vrna_fold_compound_t according to provided, or default model details. More...
void | vrna_exp_params_reset (vrna_fold_compound_t *vc, vrna_md_t *md_p)
| Reset Boltzmann factors for partition function computations within a vrna_fold_compound_t according to provided, or default model details. More...
vrna_exp_param_t * | get_scaled_pf_parameters (void)
vrna_exp_param_t * | get_boltzmann_factors (double temperature, double betaScale, vrna_md_t md, double pf_scale)
| Get precomputed Boltzmann factors of the loop type dependent energy contributions with independent thermodynamic temperature. More...
vrna_exp_param_t * | get_boltzmann_factor_copy (vrna_exp_param_t *parameters)
| Get a copy of already precomputed Boltzmann factors. More...
vrna_exp_param_t * | get_scaled_alipf_parameters (unsigned int n_seq)
| Get precomputed Boltzmann factors of the loop type dependent energy contributions (alifold variant) More...
vrna_exp_param_t * | get_boltzmann_factors_ali (unsigned int n_seq, double temperature, double betaScale, vrna_md_t md, double pf_scale)
| Get precomputed Boltzmann factors of the loop type dependent energy contributions (alifold variant) with independent thermodynamic temperature. More...
vrna_param_t * | scale_parameters (void)
| Get precomputed energy contributions for all the known loop types. More...
vrna_param_t * | get_scaled_parameters (double temperature, vrna_md_t md)
| Get precomputed energy contributions for all the known loop types. More...

## Detailed Description

All relevant functions to retrieve and copy precalculated energy parameter sets as well as reading/writing the energy parameter set from/to file(s).

This module covers all relevant functions for precalculation of the energy parameters necessary for the folding routines provided by RNAlib. Furthermore, the energy parameter set in the RNAlib can be easily exchanged by a user-defined one. It is also possible to write the current energy parameter set into a text file.

## Data Structure Documentation

struct vrna_param_s

The datastructure that contains temperature scaled energy parameters.

Collaboration diagram for vrna_param_s:
[legend]

### Data Fields

double | temperature
| Temperature used for loop contribution scaling.
vrna_md_t | model_details
| Model details to be used in the recursions.

struct vrna_exp_param_s

The datastructure that contains temperature scaled Boltzmann weights of the energy parameters.

Collaboration diagram for vrna_exp_param_s:
[legend]

### Data Fields

int | id
| An identifier for the data structure. More...
double | pf_scale
| Scaling factor to avoid over-/underflows.
double | temperature
| Temperature used for loop contribution scaling.
double | alpha
| Scaling factor for the thermodynamic temperature. More...
vrna_md_t | model_details
| Model details to be used in the recursions.

#### Field Documentation

int vrna_exp_param_s::id

An identifier for the data structure.

Deprecated:
  This attribute will be removed in version 3

double vrna_exp_param_s::alpha

Scaling factor for the thermodynamic temperature.

This allows for temperature scaling in Boltzmann factors independently from the energy contributions. The resulting Boltzmann factors are then computed by

## Typedef Documentation

typedef struct vrna_param_s paramT

`#include <ViennaRNA/params.h>`

Old typename of vrna_param_s.

Deprecated:
  Use vrna_param_t instead!

typedef struct vrna_exp_param_s pf_paramT

`#include <ViennaRNA/params.h>`

Old typename of #vrna_ex_param_s.

Deprecated:
  Use vrna_exp_param_t instead!

## Function Documentation

vrna_param_t* vrna_params | ( | vrna_md_t * | md | ) |

`#include <ViennaRNA/params.h>`

Get a data structure containing prescaled free energy parameters.

If a NULL pointer is passed for the model details parameter, the default model parameters are stored within the requested vrna_param_t structure.

See also
  vrna_md_t, vrna_md_set_default(), vrna_exp_params()

Parameters

  md | A pointer to the model details to store inside the structure (Maybe NULL)

Returns
  A pointer to the memory location where the requested parameters are stored

vrna_param_t* vrna_params_copy | ( | vrna_param_t * | par | ) |

`#include <ViennaRNA/params.h>`

Get a copy of the provided free energy parameters.

If NULL is passed as parameter, a default set of energy parameters is created and returned.

See also
  vrna_params(), vrna_param_t

Parameters

  par | The free energy parameters that are to be copied (Maybe NULL)

Returns
  A copy or a default set of the (provided) parameters

vrna_exp_param_t* vrna_exp_params | ( | vrna_md_t * | md | ) |

`#include <ViennaRNA/params.h>`

Get a data structure containing prescaled free energy parameters already transformed to Boltzmann factors.

This function returns a data structure that contains all necessary precomputed energy contributions for each type of loop.

In contrast to vrna_params(), the free energies within this data structure are stored as their Boltzmann factors, i.e.

where is the free energy.

If a NULL pointer is passed for the model details parameter, the default model parameters are stored within the requested vrna_exp_param_t structure.

See also
  vrna_md_t, vrna_md_set_default(), vrna_params(), vrna_rescale_pf_params()

Parameters

  md | A pointer to the model details to store inside the structure (Maybe NULL)

Returns
  A pointer to the memory location where the requested parameters are stored

vrna_exp_param_t* vrna_exp_params_comparative | ( | unsigned int | n_seq,
|  | vrna_md_t * | md
| ) |  |

`#include <ViennaRNA/params.h>`

Get a data structure containing prescaled free energy parameters already transformed to Boltzmann factors (alifold version)

If a NULL pointer is passed for the model details parameter, the default model parameters are stored within the requested vrna_exp_param_t structure.

See also
  vrna_md_t, vrna_md_set_default(), vrna_exp_params(), vrna_params()

Parameters

  n_seq | The number of sequences in the alignment
  md | A pointer to the model details to store inside the structure (Maybe NULL)

Returns
  A pointer to the memory location where the requested parameters are stored

vrna_exp_param_t* vrna_exp_params_copy | ( | vrna_exp_param_t * | par | ) |

`#include <ViennaRNA/params.h>`

Get a copy of the provided free energy parameters (provided as Boltzmann factors)

If NULL is passed as parameter, a default set of energy parameters is created and returned.

See also
  vrna_exp_params(), vrna_exp_param_t

Parameters

  par | The free energy parameters that are to be copied (Maybe NULL)

Returns
  A copy or a default set of the (provided) parameters

void vrna_params_subst | ( | vrna_fold_compound_t * | vc,
|  | vrna_param_t * | par
| ) |  |

`#include <ViennaRNA/params.h>`

Update/Reset energy parameters data structure within a vrna_fold_compound_t.

Passing NULL as second argument leads to a reset of the energy parameters within vc to their default values. Otherwise, the energy parameters provided will be copied over into vc.

See also
  vrna_params_reset(), vrna_param_t, vrna_md_t, vrna_params()

Parameters

  vc | The vrna_fold_compound_t that is about to receive updated energy parameters
  par | The energy parameters used to substitute those within vc (Maybe NULL)

void vrna_exp_params_subst | ( | vrna_fold_compound_t * | vc,
|  | vrna_exp_param_t * | params
| ) |  |

`#include <ViennaRNA/params.h>`

Update the energy parameters for subsequent partition function computations.

This function can be used to properly assign new energy parameters for partition function computations to a vrna_fold_compound_t. For this purpose, the data of the provided pointer `params` will be copied into `vc` and a recomputation of the partition function scaling factor is issued, if the `pf_scale` attribute of `params` is less than `1.0`.

Passing NULL as second argument leads to a reset of the energy parameters within vc to their default values

See also
  vrna_exp_params_reset(), vrna_exp_params_rescale(), vrna_exp_param_t, vrna_md_t, vrna_exp_params()

Parameters

  vc | The fold compound data structure
  params | A pointer to the new energy parameters

void vrna_exp_params_rescale | ( | vrna_fold_compound_t * | vc,
|  | double * | mfe
| ) |  |

`#include <ViennaRNA/params.h>`

Rescale Boltzmann factors for partition function computations.

This function may be used to (automatically) rescale the Boltzmann factors used in partition function computations. Since partition functions over subsequences can easily become extremely large, the RNAlib internally rescales them to avoid numerical over- and/or underflow. Therefore, a proper scaling factor needs to be chosen that in turn is then used to normalize the corresponding partition functions .

This function provides two ways to automatically adjust the scaling factor.

1. Automatic guess
2. Automatic adjustment according to MFE

Passing `NULL` as second parameter activates the automatic guess mode. Here, the scaling factor is recomputed according to a mean free energy of `184.3*length` cal for random sequences.

Note
  This recomputation only takes place if the `pf_scale` attribute of the `exp_params` datastructure contained in `vc` has a value below `1.0`.

On the other hand, if the MFE for a sequence is known, it can be used to recompute a more robust scaling factor, since it represents the lowest free energy of the entire ensemble of structures, i.e. the highest Boltzmann factor. To activate this second mode of automatic adjustment according to MFE, a pointer to the MFE value needs to be passed as second argument. This value is then taken to compute the scaling factor as , where sfact is an additional scaling weight located in the vrna_md_t datastructure of `exp_params` in `vc`.

The computed scaling factor will be stored as `pf_scale` attribute of the `exp_params` datastructure in `vc`.

See also
  vrna_exp_params_subst(), vrna_md_t, vrna_exp_param_t, vrna_fold_compound_t

Parameters

  vc | The fold compound data structure
  mfe | A pointer to the MFE (in kcal/mol) or NULL

void vrna_params_reset | ( | vrna_fold_compound_t * | vc,
|  | vrna_md_t * | md_p
| ) |  |

`#include <ViennaRNA/params.h>`

Reset free energy parameters within a vrna_fold_compound_t according to provided, or default model details.

This function allow to rescale free energy parameters for subsequent structure prediction or evaluation according to a set of model details, e.g. temperature values. To do so, the caller provides either a pointer to a set of model details to be used for rescaling, or NULL if global default setting should be used.

See also
  vrna_exp_params_reset(), vrna_params_subs()

Parameters

  vc | The fold compound data structure
  md_p | A pointer to the new model details (or NULL for reset to defaults)

void vrna_exp_params_reset | ( | vrna_fold_compound_t * | vc,
|  | vrna_md_t * | md_p
| ) |  |

`#include <ViennaRNA/params.h>`

Reset Boltzmann factors for partition function computations within a vrna_fold_compound_t according to provided, or default model details.

This function allow to rescale Boltzmann factors for subsequent prartition function computations according to a set of model details, e.g. temperature values. To do so, the caller provides either a pointer to a set of model details to be used for rescaling, or NULL if global default setting should be used.

See also
  vrna_params_reset(), vrna_exp_params_subst(), vrna_exp_params_rescale()

Parameters

  vc | The fold compound data structure
  md_p | A pointer to the new model details (or NULL for reset to defaults)

vrna_exp_param_t* get_scaled_pf_parameters | ( | void |  | ) |

`#include <ViennaRNA/params.h>`

get a datastructure of type vrna_exp_param_t which contains the Boltzmann weights of several energy parameters scaled according to the current temperature

Deprecated:
  Use vrna_exp_params() instead!

Returns
  The datastructure containing Boltzmann weights for use in partition function calculations

vrna_exp_param_t* get_boltzmann_factors | ( | double | temperature,
|  | double | betaScale,
|  | vrna_md_t | md,
|  | double | pf_scale
| ) |  |

`#include <ViennaRNA/params.h>`

Get precomputed Boltzmann factors of the loop type dependent energy contributions with independent thermodynamic temperature.

This function returns a data structure that contains all necessary precalculated Boltzmann factors for each loop type contribution.
In contrast to get_scaled_pf_parameters(), this function enables setting of independent temperatures for both, the individual energy contributions as well as the thermodynamic temperature used in

Deprecated:
  Use vrna_exp_params() instead!

See also
  get_scaled_pf_parameters(), get_boltzmann_factor_copy()

Parameters

  temperature | The temperature in degrees Celcius used for (re-)scaling the energy contributions
  betaScale | A scaling value that is used as a multiplication factor for the absolute temperature of the system
  md | The model details to be used
  pf_scale | The scaling factor for the Boltzmann factors

Returns
  A set of precomputed Boltzmann factors

vrna_exp_param_t* get_boltzmann_factor_copy | ( | vrna_exp_param_t * | parameters | ) |

`#include <ViennaRNA/params.h>`

Get a copy of already precomputed Boltzmann factors.

Deprecated:
  Use vrna_exp_params_copy() instead!

See also
  get_boltzmann_factors(), get_scaled_pf_parameters()

Parameters

  parameters | The input data structure that shall be copied

Returns
  A copy of the provided Boltzmann factor dataset

vrna_exp_param_t* get_scaled_alipf_parameters | ( | unsigned int | n_seq | ) |

`#include <ViennaRNA/params.h>`

Get precomputed Boltzmann factors of the loop type dependent energy contributions (alifold variant)

Deprecated:
  Use vrna_exp_params_comparative() instead!

vrna_exp_param_t* get_boltzmann_factors_ali | ( | unsigned int | n_seq,
|  | double | temperature,
|  | double | betaScale,
|  | vrna_md_t | md,
|  | double | pf_scale
| ) |  |

`#include <ViennaRNA/params.h>`

Get precomputed Boltzmann factors of the loop type dependent energy contributions (alifold variant) with independent thermodynamic temperature.

Deprecated:
  Use vrna_exp_params_comparative() instead!

vrna_param_t* scale_parameters | ( | void |  | ) |

`#include <ViennaRNA/params.h>`

Get precomputed energy contributions for all the known loop types.

Note
  OpenMP: This function relies on several global model settings variables and thus is not to be considered threadsafe. See get_scaled_parameters() for a completely threadsafe implementation.

Deprecated:
  Use vrna_params() instead!

Returns
  A set of precomputed energy contributions

vrna_param_t* get_scaled_parameters | ( | double | temperature,
|  | vrna_md_t | md
| ) |  |

`#include <ViennaRNA/params.h>`

Get precomputed energy contributions for all the known loop types.

Call this function to retrieve precomputed energy contributions, i.e. scaled according to the temperature passed. Furthermore, this function assumes a data structure that contains the model details as well, such that subsequent folding recursions are able to retrieve the correct model settings

Deprecated:
  Use vrna_params() instead!

See also
  vrna_md_t, set_model_details()

Parameters

  temperature | The temperature in degrees Celcius
  md | The model details

Returns
  precomputed energy contributions and model settings