Suboptimals and Representative Structures#

Sample and enumerate suboptimal secondary structures from RNA sequence data.

Suboptimal Structures sensu Zuker#

Functions

SOLUTION *zukersubopt(const char *string)#

Compute Zuker type suboptimal structures.

#include <ViennaRNA/subopt/wuchty.h>

Compute Suboptimal structures according to M. Zuker, i.e. for every possible base pair the minimum energy structure containing the resp. base pair. Returns a list of these structures and their energies.

Deprecated:: use vrna_zukersubopt() instead

Parameters:

string – RNA sequence

Returns:

List of zuker suboptimal structures

SOLUTION *zukersubopt_par(const char *string, vrna_param_t *parameters)#

Compute Zuker type suboptimal structures.

#include <ViennaRNA/subopt/wuchty.h>

Deprecated:: use vrna_zukersubopt() instead

vrna_subopt_solution_t *vrna_subopt_zuker(vrna_fold_compound_t *fc)#

Compute Zuker type suboptimal structures.

#include <ViennaRNA/subopt/zuker.h>

Compute Suboptimal structures according to Zuker [1989] , i.e. for every possible base pair the minimum energy structure containing the resp. base pair. Returns a list of these structures and their energies.

SWIG Wrapper Notes:: This function is attached as method subopt_zuker() to objects of type fold_compound. See, e.g. RNA.fold_compound.subopt_zuker() in the The RNA Python module.

Parameters:

fc – fold compound

Returns:

List of zuker suboptimal structures

Suboptimal Structures within an Energy Band around the MFE#

Typedefs

typedef void (*vrna_subopt_result_f)(const char *structure, float energy, void *data)#

Callback for vrna_subopt_cb().

#include <ViennaRNA/subopt/basic.h>

Notes on Callback Functions:: This function will be called for each suboptimal secondary structure that is successfully backtraced.

See also

vrna_subopt_cb()

Param structure:: The suboptimal secondary structure in dot-bracket notation
Param energy:: The free energy of the secondary structure in kcal/mol
Param data:: Some arbitrary, auxiliary data address as passed to vrna_subopt_cb()

Functions

vrna_subopt_solution_t *vrna_subopt(vrna_fold_compound_t *fc, int delta, int sorted, FILE *fp)#

Returns list of subopt structures or writes to fp.

#include <ViennaRNA/subopt/wuchty.h>

This function produces all suboptimal secondary structures within ‘delta’ * 0.01 kcal/mol of the optimum, see Wuchty et al. [1999] . The results are either directly written to a ‘fp’ (if ‘fp’ is not NULL), or (fp==NULL) returned in a vrna_subopt_solution_t * list terminated by an entry were the ‘structure’ member is NULL.

SWIG Wrapper Notes:: This function is attached as method subopt() to objects of type fold_compound. See, e.g. RNA.fold_compound.subopt() in the The RNA Python module.

See also

vrna_subopt_cb(), vrna_subopt_zuker()

Note

This function requires all multibranch loop DP matrices for unique multibranch loop backtracing. Therefore, the supplied vrna_fold_compound_t fc (argument 1) must be initialized with vrna_md_t.uniq_ML = 1, for instance like this:

vrna_md_t md;
vrna_md_set_default(&md);
md.uniq_ML = 1;

vrna_fold_compound_t *fc=vrna_fold_compound("GGGGGGAAAAAACCCCCC", &md, VRNA_OPTION_DEFAULT);

Parameters:

fc
delta
sorted – Sort results by energy in ascending order
fp

Returns:

void vrna_subopt_cb(vrna_fold_compound_t *fc, int delta, vrna_subopt_result_f cb, void *data)#

Generate suboptimal structures within an energy band arround the MFE.

#include <ViennaRNA/subopt/wuchty.h>

This is the most generic implementation of the suboptimal structure generator according to Wuchty et al. [1999] . Identical to vrna_subopt(), it computes all secondary structures within an energy band delta arround the MFE. However, this function does not print the resulting structures and their corresponding free energies to a file pointer, or returns them as a list. Instead, it calls a user-provided callback function which it passes the structure in dot-bracket format, the corresponding free energy in kcal/mol, and a user-provided data structure each time a structure was backtracked successfully. This function indicates the final output, i.e. the end of the backtracking procedure by passing NULL instead of an actual dot-bracket string to the callback.

SWIG Wrapper Notes:: This function is attached as method subopt_cb() to objects of type fold_compound. See, e.g. RNA.fold_compound.subopt_cb() in the The RNA Python module.

Note

This function requires all multibranch loop DP matrices for unique multibranch loop backtracing. Therefore, the supplied vrna_fold_compound_t fc (argument 1) must be initialized with vrna_md_t.uniq_ML = 1, for instance like this:

vrna_md_t md;
vrna_md_set_default(&md);
md.uniq_ML = 1;

vrna_fold_compound_t *fc=vrna_fold_compound("GGGGGGAAAAAACCCCCC", &md, VRNA_OPTION_DEFAULT);

Parameters:

fc – fold compount with the sequence data
delta – Energy band arround the MFE in 10cal/mol, i.e. deka-calories
cb – Pointer to a callback function that handles the backtracked structure and its free energy in kcal/mol
data – Pointer to some data structure that is passed along to the callback

SOLUTION *subopt(char *seq, char *structure, int delta, FILE *fp)#

Returns list of subopt structures or writes to fp.

#include <ViennaRNA/subopt/wuchty.h>

This function produces all suboptimal secondary structures within ‘delta’ * 0.01 kcal/mol of the optimum. The results are either directly written to a ‘fp’ (if ‘fp’ is not NULL), or (fp==NULL) returned in a SOLUTION * list terminated by an entry were the ‘structure’ pointer is NULL.

Parameters:

seq
structure
delta
fp

Returns:

SOLUTION *subopt_par(char *seq, char *structure, vrna_param_t *parameters, int delta, int is_constrained, int is_circular, FILE *fp)#

Returns list of subopt structures or writes to fp.

#include <ViennaRNA/subopt/wuchty.h>

SOLUTION *subopt_circ(char *seq, char *sequence, int delta, FILE *fp)#

Returns list of circular subopt structures or writes to fp.

#include <ViennaRNA/subopt/wuchty.h>

This function is similar to subopt() but calculates secondary structures assuming the RNA sequence to be circular instead of linear

Parameters:

seq
sequence
delta
fp

Returns:

Variables

double print_energy#

printing threshold for use with logML

#include <ViennaRNA/subopt/wuchty.h>

int subopt_sorted#

Sort output by energy.

#include <ViennaRNA/subopt/wuchty.h>

Boltzmann Sampling#

Draw random structure samples from the ensemble

Functions to draw random structure samples from the ensemble according to their equilibrium probability.

Defines

VRNA_PBACKTRACK_DEFAULT#

Boltzmann sampling flag indicating default backtracing mode.

#include <ViennaRNA/sampling/basic.h>

VRNA_PBACKTRACK_NON_REDUNDANT#

Boltzmann sampling flag indicating non-redundant backtracing mode.

#include <ViennaRNA/sampling/basic.h>

This flag will turn the Boltzmann sampling into non-redundant backtracing mode along the lines of Michálik et al. [2017]

Typedefs

typedef void (*vrna_bs_result_f)(const char *structure, void *data)#

Callback for Boltzmann sampling.

#include <ViennaRNA/sampling/basic.h>

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

Param structure:: The secondary structure in dot-bracket notation
Param data:: Some arbitrary, auxiliary data address as provided to the calling function

typedef void vrna_boltzmann_sampling_callback(const char *structure, void *data)#

#include <ViennaRNA/sampling/basic.h>

typedef struct vrna_pbacktrack_memory_s *vrna_pbacktrack_mem_t#

Boltzmann sampling memory data structure.

#include <ViennaRNA/sampling/basic.h>

This structure is required for properly resuming a previous sampling round in specialized Boltzmann sampling, such as non-redundant backtracking.

Initialize with NULL and pass its address to the corresponding functions vrna_pbacktrack5_resume(), etc.

Note

Do not forget to release memory occupied by this data structure before losing its context! Use vrna_pbacktrack_mem_free().

Functions

char *vrna_pbacktrack5(vrna_fold_compound_t *fc, unsigned int length)#

Sample a secondary structure of a subsequence from the Boltzmann ensemble according its probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a secondary structure. The parameter length specifies the length of the substructure starting from the 5’ end.

The structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack5() to objects of type fold_compound. See, e.g. RNA.fold_compound.pbacktrack5() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Parameters:

fc – The fold compound data structure
length – The length of the subsequence to consider (starting with 5’ end)

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

A sampled secondary structure in dot-bracket notation (or NULL on error)

char **vrna_pbacktrack5_num(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, unsigned int options)#

Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures. The parameter length specifies the length of the substructure starting from the 5’ end.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack5() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. See, e.g. RNA.fold_compound.pbacktrack5() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
length – The length of the subsequence to consider (starting with 5’ end)
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error)

unsigned int vrna_pbacktrack5_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, vrna_bs_result_f cb, void *data, unsigned int options)#

Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures. The parameter length specifies the length of the substructure starting from the 5’ end.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

In contrast to vrna_pbacktrack5() and vrna_pbacktrack5_num() this function yields the structure samples through a callback mechanism.

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack5() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. See, e.g. RNA.fold_compound.pbacktrack5() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
length – The length of the subsequence to consider (starting with 5’ end)
cb – The callback that receives the sampled structure
data – A data structure passed through to the callback cb
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

The number of structures actually backtraced

char **vrna_pbacktrack5_resume(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, vrna_pbacktrack_mem_t *nr_mem, unsigned int options)#

Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures. The parameter length specifies the length of the substructure starting from the 5’ end.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[ p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

In contrast to vrna_pbacktrack5_cb() this function allows for resuming a previous sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. For that purpose, the user passes the address of a Boltzmann sampling data structure (vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each successive call to vrna_pbacktrack5_resume_cb() or vrna_pbacktrack5_resume().

A successive sample call to this function may look like:

vrna_pbacktrack_mem_t nonredundant_memory = NULL;

// sample the first 100 structures
vrna_pbacktrack5_resume(fc,
                        100,
                        fc->length,
                        &nonredundant_memory,
                        options);

// sample another 500 structures
vrna_pbacktrack5_resume(fc,
                        500,
                        fc->length,
                        &nonredundant_memory,
                        options);

// release memory occupied by the non-redundant memory data structure
vrna_pbacktrack_mem_free(nonredundant_memory);

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack5() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. In addition to the list of structures, this function also returns the nr_mem data structure as first return value. See, e.g. RNA.fold_compound.pbacktrack5() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
length – The length of the subsequence to consider (starting with 5’ end)
nr_mem – The address of the Boltzmann sampling memory data structure
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error)

unsigned int vrna_pbacktrack5_resume_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, vrna_bs_result_f cb, void *data, vrna_pbacktrack_mem_t *nr_mem, unsigned int options)#

Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures. The parameter length specifies the length of the substructure starting from the 5’ end.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[ p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

In contrast to vrna_pbacktrack5_resume() this function yields the structure samples through a callback mechanism.

A successive sample call to this function may look like:

vrna_pbacktrack_mem_t nonredundant_memory = NULL;

// sample the first 100 structures
vrna_pbacktrack5_resume_cb(fc,
                           100,
                           fc->length,
                           &callback_function,
                           (void *)&callback_data,
                           &nonredundant_memory,
                           options);

// sample another 500 structures
vrna_pbacktrack5_resume_cb(fc,
                           500,
                           fc->length,
                           &callback_function,
                           (void *)&callback_data,
                           &nonredundant_memory,
                           options);

// release memory occupied by the non-redundant memory data structure
vrna_pbacktrack_mem_free(nonredundant_memory);

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack5() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. In addition to the number of structures backtraced, this function also returns the nr_mem data structure as first return value. See, e.g. RNA.fold_compound.pbacktrack5() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
length – The length of the subsequence to consider (starting with 5’ end)
cb – The callback that receives the sampled structure
data – A data structure passed through to the callback cb
nr_mem – The address of the Boltzmann sampling memory data structure
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

The number of structures actually backtraced

char *vrna_pbacktrack(vrna_fold_compound_t *fc)#

Sample a secondary structure from the Boltzmann ensemble according its probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a secondary structure.

The structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound. See, e.g. RNA.fold_compound.pbacktrack() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Parameters:

fc – The fold compound data structure

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

A sampled secondary structure in dot-bracket notation (or NULL on error)

char **vrna_pbacktrack_num(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int options)#

Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. See, e.g. RNA.fold_compound.pbacktrack() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error)

unsigned int vrna_pbacktrack_cb(vrna_fold_compound_t *fc, unsigned int num_samples, vrna_bs_result_f cb, void *data, unsigned int options)#

Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

In contrast to vrna_pbacktrack() and vrna_pbacktrack_num() this function yields the structure samples through a callback mechanism.

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. See, e.g. RNA.fold_compound.pbacktrack() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
cb – The callback that receives the sampled structure
data – A data structure passed through to the callback cb
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

The number of structures actually backtraced

char **vrna_pbacktrack_resume(vrna_fold_compound_t *fc, unsigned int num_samples, vrna_pbacktrack_mem_t *nr_mem, unsigned int options)#

Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[ p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

In contrast to vrna_pbacktrack_cb() this function allows for resuming a previous sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. For that purpose, the user passes the address of a Boltzmann sampling data structure (vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each successive call to vrna_pbacktrack_resume_cb() or vrna_pbacktrack_resume().

A successive sample call to this function may look like:

vrna_pbacktrack_mem_t nonredundant_memory = NULL;

// sample the first 100 structures
vrna_pbacktrack_resume(fc,
                       100,
                       &nonredundant_memory,
                       options);

// sample another 500 structures
vrna_pbacktrack_resume(fc,
                       500,
                       &nonredundant_memory,
                       options);

// release memory occupied by the non-redundant memory data structure
vrna_pbacktrack_mem_free(nonredundant_memory);

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. In addition to the list of structures, this function also returns the nr_mem data structure as first return value. See, e.g. RNA.fold_compound.pbacktrack() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
nr_mem – The address of the Boltzmann sampling memory data structure
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error)

unsigned int vrna_pbacktrack_resume_cb(vrna_fold_compound_t *fc, unsigned int num_samples, vrna_bs_result_f cb, void *data, vrna_pbacktrack_mem_t *nr_mem, unsigned int options)#

Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[ p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

In contrast to vrna_pbacktrack5_resume() this function yields the structure samples through a callback mechanism.

A successive sample call to this function may look like:

vrna_pbacktrack_mem_t nonredundant_memory = NULL;

// sample the first 100 structures
vrna_pbacktrack5_resume_cb(fc,
                           100,
                           &callback_function,
                           (void *)&callback_data,
                           &nonredundant_memory,
                           options);

// sample another 500 structures
vrna_pbacktrack5_resume_cb(fc,
                           500,
                           &callback_function,
                           (void *)&callback_data,
                           &nonredundant_memory,
                           options);

// release memory occupied by the non-redundant memory data structure
vrna_pbacktrack_mem_free(nonredundant_memory);

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. In addition to the number of structures backtraced, this function also returns the nr_mem data structure as first return value. See, e.g. RNA.fold_compound.pbacktrack() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
cb – The callback that receives the sampled structure
data – A data structure passed through to the callback cb
nr_mem – The address of the Boltzmann sampling memory data structure
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

The number of structures actually backtraced

char *vrna_pbacktrack_sub(vrna_fold_compound_t *fc, unsigned int start, unsigned int end)#

Sample a secondary structure of a subsequence from the Boltzmann ensemble according its probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a secondary structure. The parameters start and end specify the interval \( [start:end] \) of the subsequence with \( 1 \leq start < end \leq n\) for sequence length \( n \), the structure \( s_{start,end} \) should be drawn from.

The resulting substructure \( s_{start,end} \) with free energy \( E(s_{start, end}) \) is picked from the Boltzmann distributed sub ensemble of all structures within the interval \( [start:end] \) according to its probability

\[p(s_{start,end}) = \frac{exp(-E(s_{start,end}) / kT)}{Z_{start,end}} \]

with partition function \( Z_{start,end} = \sum_{s_{start,end}} exp(-E(s_{start,end}) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack_sub() to objects of type fold_compound. See, e.g. RNA.fold_compound.pbacktrack_sub() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Parameters:

fc – The fold compound data structure
start – The start of the subsequence to consider, i.e. 5’-end position(1-based)
end – The end of the subsequence to consider, i.e. 3’-end position (1-based)

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

A sampled secondary structure in dot-bracket notation (or NULL on error)

char **vrna_pbacktrack_sub_num(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, unsigned int options)#

Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures. The parameter length specifies the length of the substructure starting from the 5’ end.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack_sub() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. See, e.g. RNA.fold_compound.pbacktrack_sub() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
start – The start of the subsequence to consider, i.e. 5’-end position(1-based)
end – The end of the subsequence to consider, i.e. 3’-end position (1-based)
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error)

unsigned int vrna_pbacktrack_sub_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, vrna_bs_result_f cb, void *data, unsigned int options)#

Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures. The parameter length specifies the length of the substructure starting from the 5’ end.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

In contrast to vrna_pbacktrack5() and vrna_pbacktrack5_num() this function yields the structure samples through a callback mechanism.

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. See, e.g. RNA.fold_compound.pbacktrack() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
start – The start of the subsequence to consider, i.e. 5’-end position(1-based)
end – The end of the subsequence to consider, i.e. 3’-end position (1-based)
cb – The callback that receives the sampled structure
data – A data structure passed through to the callback cb
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

The number of structures actually backtraced

char **vrna_pbacktrack_sub_resume(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, vrna_pbacktrack_mem_t *nr_mem, unsigned int options)#

Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures. The parameter length specifies the length of the substructure starting from the 5’ end.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[ p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

In contrast to vrna_pbacktrack5_cb() this function allows for resuming a previous sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. For that purpose, the user passes the address of a Boltzmann sampling data structure (vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each successive call to vrna_pbacktrack5_resume_cb() or vrna_pbacktrack5_resume().

A successive sample call to this function may look like:

vrna_pbacktrack_mem_t nonredundant_memory = NULL;

// sample the first 100 structures
vrna_pbacktrack5_resume(fc,
                        100,
                        fc->length,
                        &nonredundant_memory,
                        options);

// sample another 500 structures
vrna_pbacktrack5_resume(fc,
                        500,
                        fc->length,
                        &nonredundant_memory,
                        options);

// release memory occupied by the non-redundant memory data structure
vrna_pbacktrack_mem_free(nonredundant_memory);

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack_sub() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. In addition to the list of structures, this function also returns the nr_mem data structure as first return value. See, e.g. RNA.fold_compound.pbacktrack_sub() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
start – The start of the subsequence to consider, i.e. 5’-end position(1-based)
end – The end of the subsequence to consider, i.e. 3’-end position (1-based)
nr_mem – The address of the Boltzmann sampling memory data structure
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error)

unsigned int vrna_pbacktrack_sub_resume_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, vrna_bs_result_f cb, void *data, vrna_pbacktrack_mem_t *nr_mem, unsigned int options)#

Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability.

#include <ViennaRNA/sampling/basic.h>

Perform a probabilistic (stochastic) backtracing in the partition function DP arrays to obtain a set of num_samples secondary structures. The parameter length specifies the length of the substructure starting from the 5’ end.

Any structure \( s \) with free energy \( E(s) \) is picked from the Boltzmann distributed ensemble according to its probability

\[ p(s) = \frac{exp(-E(s) / kT)}{Z} \]

with partition function \( Z = \sum_s exp(-E(s) / kT) \), Boltzmann constant \( k \) and thermodynamic temperature \( T \).

Using the options flag one can switch between regular (VRNA_PBACKTRACK_DEFAULT) backtracing mode, and non-redundant sampling (VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michálik et al. [2017] .

In contrast to vrna_pbacktrack5_resume() this function yields the structure samples through a callback mechanism.

A successive sample call to this function may look like:

vrna_pbacktrack_mem_t nonredundant_memory = NULL;

// sample the first 100 structures
vrna_pbacktrack5_resume_cb(fc,
                           100,
                           fc->length,
                           &callback_function,
                           (void *)&callback_data,
                           &nonredundant_memory,
                           options);

// sample another 500 structures
vrna_pbacktrack5_resume_cb(fc,
                           500,
                           fc->length,
                           &callback_function,
                           (void *)&callback_data,
                           &nonredundant_memory,
                           options);

// release memory occupied by the non-redundant memory data structure
vrna_pbacktrack_mem_free(nonredundant_memory);

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack_sub() to objects of type fold_compound with optional last argument options = VRNA_PBACKTRACK_DEFAULT. In addition to the number of structures backtraced, this function also returns the nr_mem data structure as first return value. See, e.g. RNA.fold_compound.pbacktrack_sub() in the The RNA Python module and the Boltzmann Sampling Python examples .

Note

This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.

Warning

In non-redundant sampling mode (VRNA_PBACKTRACK_NON_REDUNDANT), this function may not yield the full number of requested samples. This may happen if a) the number of requested structures is larger than the total number of structuresin the ensemble, b) numeric instabilities prevent the backtracking function to enumerate structures with high free energies, or c) any other error occurs.

Parameters:

fc – The fold compound data structure
num_samples – The size of the sample set, i.e. number of structures
start – The start of the subsequence to consider, i.e. 5’-end position(1-based)
end – The end of the subsequence to consider, i.e. 3’-end position (1-based)
cb – The callback that receives the sampled structure
data – A data structure passed through to the callback cb
nr_mem – The address of the Boltzmann sampling memory data structure
options – A bitwise OR-flag indicating the backtracing mode.

Pre:

Unique multiloop decomposition has to be active upon creation of fc with vrna_fold_compound() or similar. This can be done easily by passing vrna_fold_compound() a model details parameter with vrna_md_t.uniq_ML = 1. vrna_pf() has to be called first to fill the partition function matrices

Returns:

The number of structures actually backtraced

void vrna_pbacktrack_mem_free(vrna_pbacktrack_mem_t s)#

Release memory occupied by a Boltzmann sampling memory data structure.

#include <ViennaRNA/sampling/basic.h>

Parameters:

s – The non-redundancy memory data structure

Maximum Expected Accuracy (MEA)#

Functions

char *vrna_MEA(vrna_fold_compound_t *fc, double gamma, float *mea)#

Compute a MEA (maximum expected accuracy) structure.

#include <ViennaRNA/structures/mea.h>

The algorithm maximizes the expected accuracy

\[ A(S) = \sum_{(i,j) \in S} 2 \gamma p_{ij} + \sum_{i \notin S} p^u_i \]

Higher values of \(\gamma\) result in more base pairs of lower probability and thus higher sensitivity. Low values of \(\gamma\) result in structures containing only highly likely pairs (high specificity). The code of the MEA function also demonstrates the use of sparse dynamic programming scheme to reduce the time and memory complexity of folding.

SWIG Wrapper Notes:: This function is attached as overloaded method MEA(gamma = 1.) to objects of type fold_compound. Note, that it returns the MEA structure and MEA value as a tuple (MEA_structure, MEA). See, e.g. RNA.fold_compound.MEA() in the The RNA Python module.

Parameters:

fc – The fold compound data structure with pre-filled base pair probability matrix
gamma – The weighting factor for base pairs vs. unpaired nucleotides
mea – A pointer to a variable where the MEA value will be written to

Pre:

vrna_pf() must be executed on input parameter fc

Returns:

An MEA structure (or NULL on any error)

char *vrna_MEA_from_plist(vrna_ep_t *plist, const char *sequence, double gamma, vrna_md_t *md, float *mea)#

Compute a MEA (maximum expected accuracy) structure from a list of probabilities.

#include <ViennaRNA/structures/mea.h>

The algorithm maximizes the expected accuracy

\[ A(S) = \sum_{(i,j) \in S} 2 \gamma p_{ij} + \sum_{i \notin S} p^u_i \]

Higher values of \(\gamma\) result in more base pairs of lower probability and thus higher sensitivity. Low values of \(\gamma\) result in structures containing only highly likely pairs (high specificity). The code of the MEA function also demonstrates the use of sparse dynamic programming scheme to reduce the time and memory complexity of folding.

SWIG Wrapper Notes:: This function is available as overloaded function MEA_from_plist(gamma = 1., md = NULL). Note, that it returns the MEA structure and MEA value as a tuple (MEA_structure, MEA). See, e.g. RNA.MEA_from_plist() in the The RNA Python module.

Note

The unpaired probabilities \(p^u_i = 1 - \sum_{j \neq i} p_{ij}\) are usually computed from the supplied pairing probabilities \(p_{ij}\) as stored in plist entries of type VRNA_PLIST_TYPE_BASEPAIR. To overwrite individual \(p^u_o\) values simply add entries with type VRNA_PLIST_TYPE_UNPAIRED To include G-Quadruplex support, the corresponding field in md must be set.

Parameters:

plist – A list of base pair probabilities the MEA structure is computed from
sequence – The RNA sequence that corresponds to the list of probability values
gamma – The weighting factor for base pairs vs. unpaired nucleotides
md – A model details data structure (maybe NULL)
mea – A pointer to a variable where the MEA value will be written to

Returns:

An MEA structure (or NULL on any error)

float MEA(plist *p, char *structure, double gamma)#

Computes a MEA (maximum expected accuracy) structure.

#include <ViennaRNA/structures/mea.h>

The algorithm maximizes the expected accuracy

\[ A(S) = \sum_{(i,j) \in S} 2 \gamma p_{ij} + \sum_{i \notin S} p^u_i \]

Higher values of \(\gamma\) result in more base pairs of lower probability and thus higher sensitivity. Low values of \(\gamma\) result in structures containing only highly likely pairs (high specificity). The code of the MEA function also demonstrates the use of sparse dynamic programming scheme to reduce the time and memory complexity of folding.

Deprecated:: Use vrna_MEA() or vrna_MEA_from_plist() instead!

The Centroid Structure#

Functions

char *vrna_centroid(vrna_fold_compound_t *fc, double *dist)#

Get the centroid structure of the ensemble.

#include <ViennaRNA/structures/centroid.h>

The centroid is the structure with the minimal average distance to all other structures \( <d(S)> = \sum_{(i,j) \in S} (1-p_{ij}) + \sum_{(i,j) \notin S} p_{ij} \) Thus, the centroid is simply the structure containing all pairs with \(p_ij>0.5\) The distance of the centroid to the ensemble is written to the memory adressed by dist.

Parameters:

fc – [in] The fold compound data structure
dist – [out] A pointer to the distance variable where the centroid distance will be written to

Returns:

The centroid structure of the ensemble in dot-bracket notation (NULL on error)

char *vrna_centroid_from_plist(int length, double *dist, vrna_ep_t *pl)#

Get the centroid structure of the ensemble.

#include <ViennaRNA/structures/centroid.h>

This function is a threadsafe replacement for centroid() with a vrna_ep_t input

The centroid is the structure with the minimal average distance to all other structures \( <d(S)> = \sum_{(i,j) \in S} (1-p_{ij}) + \sum_{(i,j) \notin S} p_{ij} \) Thus, the centroid is simply the structure containing all pairs with \(p_ij>0.5\) The distance of the centroid to the ensemble is written to the memory adressed by dist.

Parameters:

length – [in] The length of the sequence
dist – [out] A pointer to the distance variable where the centroid distance will be written to
pl – [in] A pair list containing base pair probability information about the ensemble

Returns:

The centroid structure of the ensemble in dot-bracket notation (NULL on error)

char *vrna_centroid_from_probs(int length, double *dist, FLT_OR_DBL *probs)#

Get the centroid structure of the ensemble.

#include <ViennaRNA/structures/centroid.h>

This function is a threadsafe replacement for centroid() with a probability array input

The centroid is the structure with the minimal average distance to all other structures \( <d(S)> = \sum_{(i,j) \in S} (1-p_{ij}) + \sum_{(i,j) \notin S} p_{ij} \) Thus, the centroid is simply the structure containing all pairs with \(p_ij>0.5\) The distance of the centroid to the ensemble is written to the memory adressed by dist.

Parameters:

length – [in] The length of the sequence
dist – [out] A pointer to the distance variable where the centroid distance will be written to
probs – [in] An upper triangular matrix containing base pair probabilities (access via iindx vrna_idx_row_wise() )

Returns:

The centroid structure of the ensemble in dot-bracket notation (NULL on error)