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.
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.
See also
vrna_pbacktrack5_cb(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_resume_cb()
 Param structure:
The secondary structure in dotbracket 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 nonredundant backtracking.
Initialize with
NULL
and pass its address to the corresponding functions vrna_pbacktrack5_resume(), etc.See also
vrna_pbacktrack5_resume(), vrna_pbacktrack_resume(), vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_resume_cb(), vrna_pbacktrack_mem_free()
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 typefold_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 dotbracket 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 parameterlength
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 nonredundant 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 typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. See, e.g.RNA.fold_compound.pbacktrack5()
in the Python API and the Boltzmann Sampling Python examples .
See also
vrna_pbacktrack5(), vrna_pbacktrack5_cb(), vrna_pbacktrack_num(), VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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 ORflag 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 dotbracket 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 parameterlength
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 nonredundant 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 typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. See, e.g.RNA.fold_compound.pbacktrack5()
in the Python API and the Boltzmann Sampling Python examples .
See also
vrna_pbacktrack5(), vrna_pbacktrack5_num(), vrna_pbacktrack_cb(), VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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 ORflag 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 parameterlength
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 nonredundant 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 nonredundant backtracking. For that purpose, the user passes the address of a Boltzmann sampling data structure (vrna_pbacktrack_mem_t) which will be reused 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 nonredundant memory data structure vrna_pbacktrack_mem_free(nonredundant_memory);
 SWIG Wrapper Notes:
This function is attached as overloaded method
pbacktrack5()
to objects of typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. In addition to the list of structures, this function also returns thenr_mem
data structure as first return value. See, e.g.RNA.fold_compound.pbacktrack5()
in the Python API and the Boltzmann Sampling Python examples .
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
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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 ORflag 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 dotbracket 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 parameterlength
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 nonredundant 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 nonredundant memory data structure vrna_pbacktrack_mem_free(nonredundant_memory);
 SWIG Wrapper Notes:
This function is attached as overloaded method
pbacktrack5()
to objects of typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. In addition to the number of structures backtraced, this function also returns thenr_mem
data structure as first return value. See, e.g.RNA.fold_compound.pbacktrack5()
in the Python API and the Boltzmann Sampling Python examples .
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
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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 ORflag 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 typefold_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 dotbracket 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 nonredundant 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 typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. See, e.g.RNA.fold_compound.pbacktrack()
in the Python API and the Boltzmann Sampling Python examples .
See also
vrna_pbacktrack(), vrna_pbacktrack_cb(), vrna_pbacktrack5_num(), VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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 ORflag 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 dotbracket 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 nonredundant 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 typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. See, e.g.RNA.fold_compound.pbacktrack()
in the Python API and the Boltzmann Sampling Python examples .
See also
vrna_pbacktrack(), vrna_pbacktrack_num(), vrna_pbacktrack5_cb(), VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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 ORflag 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 nonredundant 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 nonredundant backtracking. For that purpose, the user passes the address of a Boltzmann sampling data structure (vrna_pbacktrack_mem_t) which will be reused 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 nonredundant memory data structure vrna_pbacktrack_mem_free(nonredundant_memory);
 SWIG Wrapper Notes:
This function is attached as overloaded method
pbacktrack()
to objects of typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. In addition to the list of structures, this function also returns thenr_mem
data structure as first return value. See, e.g.RNA.fold_compound.pbacktrack()
in the Python API and the Boltzmann Sampling Python examples .
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
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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 ORflag 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 dotbracket 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 nonredundant 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 nonredundant memory data structure vrna_pbacktrack_mem_free(nonredundant_memory);
 SWIG Wrapper Notes:
This function is attached as overloaded method
pbacktrack()
to objects of typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. In addition to the number of structures backtraced, this function also returns thenr_mem
data structure as first return value. See, e.g.RNA.fold_compound.pbacktrack()
in the Python API and the Boltzmann Sampling Python examples .
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
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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 ORflag 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
andend
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(1based)
end – The end of the subsequence to consider, i.e. 3’end position (1based)
 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 dotbracket 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 parameterlength
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 nonredundant 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 typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. See, e.g.RNA.fold_compound.pbacktrack_sub()
in the Python API and the Boltzmann Sampling Python examples .
See also
vrna_pbacktrack_sub(), vrna_pbacktrack_sub_cb(), vrna_pbacktrack_num(), VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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(1based)
end – The end of the subsequence to consider, i.e. 3’end position (1based)
options – A bitwise ORflag 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 dotbracket 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 parameterlength
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 nonredundant 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 typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. See, e.g.RNA.fold_compound.pbacktrack()
in the Python API and the Boltzmann Sampling Python examples .
See also
vrna_pbacktrack5(), vrna_pbacktrack5_num(), vrna_pbacktrack_cb(), VRNA_PBACKTRACK_DEFAULT, VRNA_PBACKTRACK_NON_REDUNDANT
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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(1based)
end – The end of the subsequence to consider, i.e. 3’end position (1based)
cb – The callback that receives the sampled structure
data – A data structure passed through to the callback
cb
options – A bitwise ORflag 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 parameterlength
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 nonredundant 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 nonredundant backtracking. For that purpose, the user passes the address of a Boltzmann sampling data structure (vrna_pbacktrack_mem_t) which will be reused 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 nonredundant memory data structure vrna_pbacktrack_mem_free(nonredundant_memory);
 SWIG Wrapper Notes:
This function is attached as overloaded method
pbacktrack_sub()
to objects of typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. In addition to the list of structures, this function also returns thenr_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 .
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
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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(1based)
end – The end of the subsequence to consider, i.e. 3’end position (1based)
nr_mem – The address of the Boltzmann sampling memory data structure
options – A bitwise ORflag 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 dotbracket 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 parameterlength
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 nonredundant 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 nonredundant memory data structure vrna_pbacktrack_mem_free(nonredundant_memory);
 SWIG Wrapper Notes:
This function is attached as overloaded method
pbacktrack_sub()
to objects of typefold_compound
with optional last argumentoptions
= VRNA_PBACKTRACK_DEFAULT. In addition to the number of structures backtraced, this function also returns thenr_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 .
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
Note
This function is polymorphic. It accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE.
Warning
In nonredundant 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(1based)
end – The end of the subsequence to consider, i.e. 3’end position (1based)
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 ORflag 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.
See also
vrna_pbacktrack_mem_t, vrna_pbacktrack5_resume(), vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_resume(), vrna_pbacktrack_resume_cb()
 Parameters:
s – The nonredundancy memory data structure

VRNA_PBACKTRACK_DEFAULT
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 dotbracket notation

char *pbacktrack5(char *sequence, int length)
 #include <ViennaRNA/part_func.h>
Sample a substructure 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 dotbracket 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

char *pbacktrack(char *sequence)