1 #ifndef __VIENNA_RNA_PACKAGE_PART_FUNC_CO_H__
2 #define __VIENNA_RNA_PACKAGE_PART_FUNC_CO_H__
4 #include "data_structures.h"
7 #define DEPRECATED(func) func __attribute__ ((deprecated))
9 #define DEPRECATED(func) func
13 * \addtogroup pf_cofold
14 * \brief Partition Function Cofolding
16 * To simplify the implementation the partition function computation is done
17 * internally in a null model that does not include the duplex initiation
18 * energy, i.e. the entropic penalty for producing a dimer from two
19 * monomers). The resulting free energies and pair probabilities are initially
20 * relative to that null model. In a second step the free energies can be
21 * corrected to include the dimerization penalty, and the pair probabilities
22 * can be divided into the conditional pair probabilities given that a re
23 * dimer is formed or not formed. See \cite bernhart:2006 for further details.
25 * \file part_func_co.h
27 * \brief Partition function for two RNA sequences
29 * As for folding one RNA molecule, this computes the partition function
30 * of all possible structures and the base pair probabilities. Uses the
31 * same global #pf_scale variable to avoid overflows.
33 * To simplify the implementation the partition function computation is done
34 * internally in a null model that does not include the duplex initiation
35 * energy, i.e. the entropic penalty for producing a dimer from two
36 * monomers). The resulting free energies and pair probabilities are initially
37 * relative to that null model. In a second step the free energies can be
38 * corrected to include the dimerization penalty, and the pair probabilities
39 * can be divided into the conditional pair probabilities given that a re
40 * dimer is formed or not formed.
42 * After computing the partition functions of all possible dimeres one
43 * can compute the probabilities of base pairs, the concentrations out of
44 * start concentrations and sofar and soaway.
46 * Dimer formation is inherently concentration dependent. Given the free
47 * energies of the monomers A and B and dimers AB, AA, and BB one can compute
48 * the equilibrium concentrations, given input concentrations of A and B, see
49 * e.g. Dimitrov & Zuker (2004)
53 * \brief Toggles no intrabp in 2nd mol
58 * \brief Free energies of the two monomers
60 extern double F_monomer[2];
63 * \brief Calculate partition function and base pair probabilities
65 * This is the cofold partition function folding. The second molecule starts
66 * at the #cut_point nucleotide.
68 * \note OpenMP: Since this function relies on the global parameters
69 * #do_backtrack, #dangles, #temperature and #pf_scale it is not
70 * threadsafe according to concurrent changes in these variables!
71 * Use co_pf_fold_par() instead to circumvent this issue.
73 * \see co_pf_fold_par()
75 * \param sequence Concatenated RNA sequences
76 * \param structure Will hold the structure or constraints
77 * \return cofoldF structure containing a set of energies needed for
78 * concentration computations.
80 cofoldF co_pf_fold( char *sequence,
84 * \brief Calculate partition function and base pair probabilities
86 * This is the cofold partition function folding. The second molecule starts
87 * at the #cut_point nucleotide.
89 * \see get_boltzmann_factors(), co_pf_fold()
91 * \param sequence Concatenated RNA sequences
92 * \param structure Pointer to the structure constraint
93 * \param parameters Data structure containing the precalculated Boltzmann factors
94 * \param calculate_bppm Switch to turn Base pair probability calculations on/off (0==off)
95 * \param is_constrained Switch to indicate that a structure contraint is passed via the
96 * structure argument (0==off)
97 * \return cofoldF structure containing a set of energies needed for
98 * concentration computations.
100 cofoldF co_pf_fold_par( char *sequence,
102 pf_paramT *parameters,
107 * \brief Get a pointer to the base pair probability array
109 * Accessing the base pair probabilities for a pair (i,j) is achieved by
110 * \verbatim FLT_OR_DBL *pr = export_bppm(); pr_ij = pr[iindx[i]-j]; \endverbatim
113 * \return A pointer to the base pair probability array
115 FLT_OR_DBL *export_co_bppm(void);
118 * \brief Free the memory occupied by co_pf_fold()
120 void free_co_pf_arrays(void);
123 * \brief Recalculate energy parameters
125 * This function recalculates all energy parameters given
126 * the current model settings.
128 * \note This function relies on the global variables #pf_scale, #dangles and
129 * #temperature. Thus it might not be threadsafe in certain situations.
130 * Use update_co_pf_params_par() instead.
132 * \see get_boltzmann_factors(), update_co_pf_params_par()
134 * \param length Length of the current RNA sequence
136 void update_co_pf_params(int length);
139 * \brief Recalculate energy parameters
141 * This function recalculates all energy parameters given
142 * the current model settings.
143 * It's second argument can either be NULL or a data structure
144 * containing the precomputed Boltzmann factors. In the first
145 * scenario, the necessary data structure will be created automatically
146 * according to the current global model settings, i.e. this
147 * mode might not be threadsafe.
148 * However, if the provided data structure is not NULL, threadsafety
149 * for the model parameters #dangles, #pf_scale and #temperature is regained, since their
150 * values are taken from this data structure during subsequent calculations.
152 * \see get_boltzmann_factors(), update_co_pf_params()
154 * \param length Length of the current RNA sequence
155 * \param parameters data structure containing the precomputed Boltzmann factors
157 void update_co_pf_params_par(int length,
158 pf_paramT *parameters);
161 * \brief Compute Boltzmann probabilities of dimerization without homodimers
163 * Given the pair probabilities and free energies (in the null model) for a
164 * dimer AB and the two constituent monomers A and B, compute the conditional pair
165 * probabilities given that a dimer AB actually forms.
166 * Null model pair probabilities are given as a list as produced by
167 * assign_plist_from_pr(), the dimer probabilities 'prAB' are modified in place.
169 * \param FAB free energy of dimer AB
170 * \param FEA free energy of monomer A
171 * \param FEB free energy of monomer B
172 * \param prAB pair probabilities for dimer
173 * \param prA pair probabilities monomer
174 * \param prB pair probabilities monomer
175 * \param Alength Length of molecule A
177 void compute_probabilities(double FAB,
186 * \brief Given two start monomer concentrations a and b, compute the
187 * concentrations in thermodynamic equilibrium of all dimers and the monomers.
189 * This function takes an array 'startconc' of input concentrations with alternating
190 * entries for the initial concentrations of molecules A and B (terminated by
191 * two zeroes), then computes the resulting equilibrium concentrations
192 * from the free energies for the dimers. Dimer free energies should be the
193 * dimer-only free energies, i.e. the FcAB entries from the #cofoldF struct.
195 * \param FEAB Free energy of AB dimer (FcAB entry)
196 * \param FEAA Free energy of AA dimer (FcAB entry)
197 * \param FEBB Free energy of BB dimer (FcAB entry)
198 * \param FEA Free energy of monomer A
199 * \param FEB Free energy of monomer B
200 * \param startconc List of start concentrations [a0],[b0],[a1],[b1],...,[an][bn],[0],[0]
201 * \return ConcEnt array containing the equilibrium energies and start concentrations
203 ConcEnt *get_concentrations(double FEAB,
216 #################################################
217 # DEPRECATED FUNCTIONS #
218 #################################################
222 * DO NOT USE THIS FUNCTION ANYMORE
223 * \deprecated{ This function is deprecated and will be removed soon!}
224 * use \ref assign_plist_from_pr() instead!
226 DEPRECATED(plist *get_plist( struct plist *pl,
230 * DO NOT USE THIS FUNCTION ANYMORE
231 * \deprecated{ This function is deprecated and will be removed soon!}
233 DEPRECATED(void init_co_pf_fold(int length));