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

Detailed Description

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

Collaboration diagram for Random Structure Samples from the Ensemble:

Modules
	Stochastic Backtracking of Structures from Distance Based Partitioning
	Contains functions related to stochastic backtracking from a specified distance class.

	Deprecated Interface for Stochastic Backtracking

Macros
#define	VRNA_PBACKTRACK_DEFAULT 0
	Boltzmann sampling flag indicating default backtracing mode. More...

#define	VRNA_PBACKTRACK_NON_REDUNDANT 1
	Boltzmann sampling flag indicating non-redundant backtracing mode. More...

Typedefs
typedef void(	vrna_boltzmann_sampling_callback) (const char stucture, void data)
	Callback for Boltzmann sampling. More...

typedef struct vrna_pbacktrack_memory_s *	vrna_pbacktrack_mem_t
	Boltzmann sampling memory data structure. More...

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. More...

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. More...

unsigned int	vrna_pbacktrack5_cb (vrna_fold_compound_t fc, unsigned int num_samples, unsigned int length, vrna_boltzmann_sampling_callback cb, void *data, unsigned int options)
	Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability. More...

char **	vrna_pbacktrack5_resume (vrna_fold_compound_t vc, 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. More...

unsigned int	vrna_pbacktrack5_resume_cb (vrna_fold_compound_t fc, unsigned int num_samples, unsigned int length, vrna_boltzmann_sampling_callback 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. More...

char *	vrna_pbacktrack (vrna_fold_compound_t *fc)
	Sample a secondary structure from the Boltzmann ensemble according its probability. More...

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. More...

unsigned int	vrna_pbacktrack_cb (vrna_fold_compound_t fc, unsigned int num_samples, vrna_boltzmann_sampling_callback cb, void *data, unsigned int options)
	Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability. More...

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. More...

unsigned int	vrna_pbacktrack_resume_cb (vrna_fold_compound_t fc, unsigned int num_samples, vrna_boltzmann_sampling_callback 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. More...

void	vrna_pbacktrack_mem_free (vrna_pbacktrack_mem_t s)
	Release memory occupied by a Boltzmann sampling memory data structure. More...

Macro Definition Documentation

#define VRNA_PBACKTRACK_DEFAULT 0

#include <ViennaRNA/boltzmann_sampling.h>

Boltzmann sampling flag indicating default backtracing mode.

See also: vrna_pbacktrack5_num(), vrna_pbacktrack5_cb(), vrna_pbacktrack5_resume(), vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_num(), vrna_pbacktrack_cb(), vrna_pbacktrack_resume(), vrna_pbacktrack_resume_cb()

#define VRNA_PBACKTRACK_NON_REDUNDANT 1

#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 Michalik et al. 2017 [18]

See also: vrna_pbacktrack5_num(), vrna_pbacktrack5_cb(), vrna_pbacktrack5_resume(), vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_num(), vrna_pbacktrack_cb(), vrna_pbacktrack_resume(), vrna_pbacktrack_resume_cb()

Typedef Documentation

typedef void( vrna_boltzmann_sampling_callback) (const char *stucture, 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.

See also: vrna_pbacktrack5_cb(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_resume_cb()

Parameters

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

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().

See also: vrna_pbacktrack5_resume(), vrna_pbacktrack_resume(), vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_resume_cb(), vrna_pbacktrack_mem_free()

Function Documentation

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 $ .

Precondition: 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

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

See also: vrna_pbacktrack5_num(), vrna_pbacktrack5_cb(), vrna_pbacktrack()

Parameters

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

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

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack5() to objects of type fold_compound. See also Python Examples - Boltzmann Sampling

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 Michalik et al. 2017 [18].

Precondition: 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

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.

See also: vrna_pbacktrack5(), vrna_pbacktrack5_cb(), vrna_pbacktrack_num(), VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT

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.

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

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack5() to objects of type fold_compound where the last argument options is optional with default value options = VRNA_PBACKTRACK_DEFAULT. See also Python Examples - Boltzmann Sampling

unsigned int vrna_pbacktrack5_cb	(	vrna_fold_compound_t *	fc,
		unsigned int	num_samples,
		unsigned int	length,
		vrna_boltzmann_sampling_callback *	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 Michalik et al. 2017 [18].

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

Precondition: 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

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.

See also: vrna_pbacktrack5(), vrna_pbacktrack5_num(), vrna_pbacktrack_cb(), VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT

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.

Returns: The number of structures actually backtraced

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack5() to objects of type fold_compound where the last argument options is optional with default value options = VRNA_PBACKTRACK_DEFAULT. See also Python Examples - Boltzmann Sampling

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 Michalik et al. 2017 [18].

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

Precondition: 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

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.

See also: vrna_pbacktrack5_resume_cb(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume(), vrna_pbacktrack_mem_t, VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT, vrna_pbacktrack_mem_free

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.

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

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack5() to objects of type fold_compound. In addition to the list of structures, this function also returns the nr_mem data structure as first element. See also Python Examples - Boltzmann Sampling

unsigned int vrna_pbacktrack5_resume_cb	(	vrna_fold_compound_t *	fc,
		unsigned int	num_samples,
		unsigned int	length,
		vrna_boltzmann_sampling_callback *	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 Michalik et al. 2017 [18].

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

Precondition: 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

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.

See also: vrna_pbacktrack5_resume(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume_cb(), vrna_pbacktrack_mem_t, VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT, vrna_pbacktrack_mem_free

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.

Returns: The number of structures actually backtraced

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack5() to objects of type fold_compound. In addition to the number of structures backtraced, this function also returns the nr_mem data structure as first element. See also Python Examples - Boltzmann Sampling

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 $ .

Precondition: 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

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

See also: vrna_pbacktrack5(), vrna_pbacktrack_num, vrna_pbacktrack_cb()

Parameters

fc	The fold compound data structure

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

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound. See also Python Examples - Boltzmann Sampling

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 Michalik et al. 2017 [18].

Precondition: 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

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.

See also: vrna_pbacktrack(), vrna_pbacktrack_cb(), vrna_pbacktrack5_num(), VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT

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.

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

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound where the last argument options is optional with default value options = VRNA_PBACKTRACK_DEFAULT. See also Python Examples - Boltzmann Sampling

unsigned int vrna_pbacktrack_cb	(	vrna_fold_compound_t *	fc,
		unsigned int	num_samples,
		vrna_boltzmann_sampling_callback *	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 Michalik et al. 2017 [18].

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

Precondition: 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

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.

See also: vrna_pbacktrack(), vrna_pbacktrack_num(), vrna_pbacktrack5_cb(), VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT

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.

Returns: The number of structures actually backtraced

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound where the last argument options is optional with default value options = VRNA_PBACKTRACK_DEFAULT. See also Python Examples - Boltzmann Sampling

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 Michalik et al. 2017 [18].

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

Precondition: 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

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.

See also: vrna_pbacktrack_resume_cb(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume(), vrna_pbacktrack_mem_t, VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT, vrna_pbacktrack_mem_free

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.

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

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound. In addition to the list of structures, this function also returns the nr_mem data structure as first element. See also Python Examples - Boltzmann Sampling

unsigned int vrna_pbacktrack_resume_cb	(	vrna_fold_compound_t *	fc,
		unsigned int	num_samples,
		vrna_boltzmann_sampling_callback *	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 Michalik et al. 2017 [18].

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

Precondition: 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

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.

See also: vrna_pbacktrack_resume(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_mem_t, VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT, vrna_pbacktrack_mem_free

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.

Returns: The number of structures actually backtraced

SWIG Wrapper Notes:: This function is attached as overloaded method pbacktrack() to objects of type fold_compound. In addition to the number of structures backtraced, this function also returns the nr_mem data structure as first element. See also Python Examples - Boltzmann Sampling

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.

See also: vrna_pbacktrack_mem_t, vrna_pbacktrack5_resume(), vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_resume(), vrna_pbacktrack_resume_cb()

Parameters

s	The non-redundancy memory data structure

Detailed Description

Modules

Macros

Typedefs

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation