binaries/src/ViennaRNA/H/part_func_co.h

   1 #ifndef __VIENNA_RNA_PACKAGE_PART_FUNC_CO_H__
   2 #define __VIENNA_RNA_PACKAGE_PART_FUNC_CO_H__
   3
   4 #include "data_structures.h"
   5
   6 #ifdef __GNUC__
   7 #define DEPRECATED(func) func __attribute__ ((deprecated))
   8 #else
   9 #define DEPRECATED(func) func
  10 #endif
  11
  12 /**
  13  *  \addtogroup pf_cofold
  14  *  \brief Partition Function Cofolding
  15  *
  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.
  24  *  @{
  25  *  \file part_func_co.h
  26  *
  27  *  \brief Partition function for two RNA sequences
  28  *
  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.
  32  *
  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.
  41  *
  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.
  45  *
  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)
  50  */
  51
  52 /**
  53  *  \brief Toggles no intrabp in 2nd mol
  54  */
  55 extern int    mirnatog;
  56
  57 /**
  58  *  \brief Free energies of the two monomers
  59  */
  60 extern double F_monomer[2];
  61
  62 /**
  63  *  \brief Calculate partition function and base pair probabilities
  64  *
  65  *  This is the cofold partition function folding. The second molecule starts
  66  *  at the #cut_point nucleotide.
  67  *
  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.
  72  *
  73  *  \see co_pf_fold_par()
  74  *
  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.
  79  */
  80 cofoldF co_pf_fold( char *sequence,
  81                     char *structure);
  82
  83 /**
  84  *  \brief Calculate partition function and base pair probabilities
  85  *
  86  *  This is the cofold partition function folding. The second molecule starts
  87  *  at the #cut_point nucleotide.
  88  *
  89  *  \see get_boltzmann_factors(), co_pf_fold()
  90  *
  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.
  99  */
 100 cofoldF co_pf_fold_par( char *sequence,
 101                         char *structure,
 102                         pf_paramT *parameters,
 103                         int calculate_bppm,
 104                         int is_constrained);
 105
 106 /**
 107  *  \brief Get a pointer to the base pair probability array
 108  *
 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
 111  *
 112  *  \see get_iindx()
 113  *  \return A pointer to the base pair probability array
 114  */
 115 FLT_OR_DBL *export_co_bppm(void);
 116
 117 /**
 118  *  \brief Free the memory occupied by co_pf_fold()
 119  */
 120 void    free_co_pf_arrays(void);
 121
 122 /**
 123  *  \brief Recalculate energy parameters
 124  *
 125  *  This function recalculates all energy parameters given
 126  *  the current model settings.
 127  *
 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.
 131  *
 132  *  \see get_boltzmann_factors(), update_co_pf_params_par()
 133  *
 134  *  \param    length      Length of the current RNA sequence
 135  */
 136 void    update_co_pf_params(int length);
 137
 138 /**
 139  *  \brief Recalculate energy parameters
 140  *
 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.
 151  *
 152  *  \see get_boltzmann_factors(), update_co_pf_params()
 153  *
 154  *  \param    length      Length of the current RNA sequence
 155  *  \param    parameters  data structure containing the precomputed Boltzmann factors
 156  */
 157 void    update_co_pf_params_par(int length,
 158                                 pf_paramT *parameters);
 159
 160 /**
 161  *  \brief Compute Boltzmann probabilities of dimerization without homodimers
 162  *
 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.
 168  *
 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
 176  */
 177 void    compute_probabilities(double FAB,
 178                               double FEA,
 179                               double FEB,
 180                               struct plist  *prAB,
 181                               struct plist  *prA,
 182                               struct plist  *prB,
 183                               int Alength);
 184
 185 /**
 186  *  \brief Given two start monomer concentrations a and b, compute the
 187  *  concentrations in thermodynamic equilibrium of all dimers and the monomers.
 188  *
 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.
 194  *
 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
 202  */
 203 ConcEnt *get_concentrations(double FEAB,
 204                             double FEAA,
 205                             double FEBB,
 206                             double FEA,
 207                             double FEB,
 208                             double *startconc);
 209
 210
 211 /**
 212  *  @}
 213  */
 214
 215 /*
 216 #################################################
 217 # DEPRECATED FUNCTIONS                          #
 218 #################################################
 219 */
 220
 221 /**
 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!
 225  */
 226 DEPRECATED(plist  *get_plist( struct plist *pl,
 227                               int length,
 228                               double cut_off));
 229 /**
 230  *  DO NOT USE THIS FUNCTION ANYMORE
 231  *  \deprecated{ This function is deprecated and will be removed soon!}
 232  */
 233 DEPRECATED(void   init_co_pf_fold(int length));
 234
 235 #endif