Random Structure Samples from the Ensemble

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

Defines

VRNA_PBACKTRACK_DEFAULT

#include <ViennaRNA/boltzmann_sampling.h>

Boltzmann sampling flag indicating default backtracing mode.

VRNA_PBACKTRACK_NON_REDUNDANT

#include <ViennaRNA/boltzmann_sampling.h>

Boltzmann sampling flag indicating non-redundant backtracing mode.

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)

#include <ViennaRNA/boltzmann_sampling.h>

Callback for Boltzmann sampling.

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

void() vrna_boltzmann_sampling_callback (const char *structure, void *data): #include <ViennaRNA/boltzmann_sampling.h>

typedef struct vrna_pbacktrack_memory_s *vrna_pbacktrack_mem_t

#include <ViennaRNA/boltzmann_sampling.h>

Boltzmann sampling memory data structure.

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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

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

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 Python API 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)

#include <ViennaRNA/boltzmann_sampling.h>

Release memory occupied by a Boltzmann sampling memory data structure.

Parameters:

s – The non-redundancy memory data structure

Deprecated API

Functions

char *pbacktrack(char *sequence)

#include <ViennaRNA/part_func.h>

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

Parameters:

sequence – The RNA sequence

Pre:

st_back has to be set to 1 before calling pf_fold() or pf_fold_par()pf_fold_par() or pf_fold() have to be called first to fill the partition function matrices

Returns:

A sampled secondary structure in dot-bracket notation

char *pbacktrack5(char *sequence, int length): #include <ViennaRNA/part_func.h>
Sample a sub-structure from the Boltzmann ensemble according its probability.

char *pbacktrack_circ(char *sequence)

#include <ViennaRNA/part_func.h>

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

This function does the same as pbacktrack() but assumes the RNA molecule to be circular

Deprecated:: Use vrna_pbacktrack() instead.

Pre:

st_back has to be set to 1 before calling pf_fold() or pf_fold_par()pf_fold_par() or pf_circ_fold() have to be called first to fill the partition function matrices

Parameters:

sequence – The RNA sequence

Returns:

A sampled secondary structure in dot-bracket notation

Variables

int st_back

Flag indicating that auxilary arrays are needed throughout the computations. This is essential for stochastic backtracking.

Set this variable to 1 prior to a call of pf_fold() to ensure that all matrices needed for stochastic backtracking are filled in the forward recursions

Deprecated:: set the uniq_ML flag in vrna_md_t before passing it to vrna_fold_compound().

See also

pbacktrack(), pbacktrack_circ