binaries/src/ViennaRNA/doc/latex/group__pf__cofold.tex

   1 \hypertarget{group__pf__cofold}{\section{Partition Function for two hybridized Sequences}
   2 \label{group__pf__cofold}\index{Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}}
   3 }
   4
   5
   6 Partition Function Cofolding.
   7
   8
   9 Collaboration diagram for Partition Function for two hybridized Sequences\-:
  10 \nopagebreak
  11 \begin{figure}[H]
  12 \begin{center}
  13 \leavevmode
  14 \includegraphics[width=350pt]{group__pf__cofold}
  15 \end{center}
  16 \end{figure}
  17 \subsection*{Files}
  18 \begin{DoxyCompactItemize}
  19 \item
  20 file \hyperlink{part__func__co_8h}{part\-\_\-func\-\_\-co.\-h}
  21 \begin{DoxyCompactList}\small\item\em Partition function for two R\-N\-A sequences. \end{DoxyCompactList}\end{DoxyCompactItemize}
  22 \subsection*{Functions}
  23 \begin{DoxyCompactItemize}
  24 \item
  25 \hyperlink{structcofoldF}{cofold\-F} \hyperlink{group__pf__cofold_gaa86a5f998789ed71813d23d7307a791b}{co\-\_\-pf\-\_\-fold} (char $\ast$sequence, char $\ast$structure)
  26 \begin{DoxyCompactList}\small\item\em Calculate partition function and base pair probabilities. \end{DoxyCompactList}\item
  27 \hyperlink{structcofoldF}{cofold\-F} \hyperlink{group__pf__cofold_gabd873b450832ab5f21101fc5ab354d21}{co\-\_\-pf\-\_\-fold\-\_\-par} (char $\ast$sequence, char $\ast$structure, \hyperlink{structpf__paramT}{pf\-\_\-param\-T} $\ast$parameters, int calculate\-\_\-bppm, int is\-\_\-constrained)
  28 \begin{DoxyCompactList}\small\item\em Calculate partition function and base pair probabilities. \end{DoxyCompactList}\item
  29 double $\ast$ \hyperlink{group__pf__cofold_ga11f0252c1d2c4697253ff4b5bd392d3c}{export\-\_\-co\-\_\-bppm} (void)
  30 \begin{DoxyCompactList}\small\item\em Get a pointer to the base pair probability array. \end{DoxyCompactList}\item
  31 \hypertarget{group__pf__cofold_gade3ce34ae8214811374b1d28a40dc247}{void \hyperlink{group__pf__cofold_gade3ce34ae8214811374b1d28a40dc247}{free\-\_\-co\-\_\-pf\-\_\-arrays} (void)}\label{group__pf__cofold_gade3ce34ae8214811374b1d28a40dc247}
  32
  33 \begin{DoxyCompactList}\small\item\em Free the memory occupied by \hyperlink{group__pf__cofold_gaa86a5f998789ed71813d23d7307a791b}{co\-\_\-pf\-\_\-fold()} \end{DoxyCompactList}\item
  34 void \hyperlink{group__pf__cofold_ga6e0f36c1f9b7d9dd4bfbad914c1119e5}{update\-\_\-co\-\_\-pf\-\_\-params} (int length)
  35 \begin{DoxyCompactList}\small\item\em Recalculate energy parameters. \end{DoxyCompactList}\item
  36 void \hyperlink{group__pf__cofold_ga117d880df45bef444d5e2785ffa40a53}{update\-\_\-co\-\_\-pf\-\_\-params\-\_\-par} (int length, \hyperlink{structpf__paramT}{pf\-\_\-param\-T} $\ast$parameters)
  37 \begin{DoxyCompactList}\small\item\em Recalculate energy parameters. \end{DoxyCompactList}\item
  38 void \hyperlink{group__pf__cofold_ga15ae04ac5ab84e876dcf0093120cb617}{compute\-\_\-probabilities} (double F\-A\-B, double F\-E\-A, double F\-E\-B, struct \hyperlink{structplist}{plist} $\ast$pr\-A\-B, struct \hyperlink{structplist}{plist} $\ast$pr\-A, struct \hyperlink{structplist}{plist} $\ast$pr\-B, int Alength)
  39 \begin{DoxyCompactList}\small\item\em Compute Boltzmann probabilities of dimerization without homodimers. \end{DoxyCompactList}\item
  40 \hyperlink{structConcEnt}{Conc\-Ent} $\ast$ \hyperlink{group__pf__cofold_ga5545cb936ac4ff93c7d699d46e72e8c7}{get\-\_\-concentrations} (double F\-E\-A\-B, double F\-E\-A\-A, double F\-E\-B\-B, double F\-E\-A, double F\-E\-B, double $\ast$startconc)
  41 \begin{DoxyCompactList}\small\item\em Given two start monomer concentrations a and b, compute the concentrations in thermodynamic equilibrium of all dimers and the monomers. \end{DoxyCompactList}\end{DoxyCompactItemize}
  42 \subsection*{Variables}
  43 \begin{DoxyCompactItemize}
  44 \item
  45 \hypertarget{group__pf__cofold_gaff27888c4088cc1f60fd59cbd589474c}{int \hyperlink{group__pf__cofold_gaff27888c4088cc1f60fd59cbd589474c}{mirnatog}}\label{group__pf__cofold_gaff27888c4088cc1f60fd59cbd589474c}
  46
  47 \begin{DoxyCompactList}\small\item\em Toggles no intrabp in 2nd mol. \end{DoxyCompactList}\item
  48 \hypertarget{group__pf__cofold_gac2d1851a710a8561390861155ca988fe}{double \hyperlink{group__pf__cofold_gac2d1851a710a8561390861155ca988fe}{F\-\_\-monomer} \mbox{[}2\mbox{]}}\label{group__pf__cofold_gac2d1851a710a8561390861155ca988fe}
  49
  50 \begin{DoxyCompactList}\small\item\em Free energies of the two monomers. \end{DoxyCompactList}\end{DoxyCompactItemize}
  51
  52
  53 \subsection{Detailed Description}
  54 Partition Function Cofolding. To simplify the implementation the partition function computation is done internally in a null model that does not include the duplex initiation energy, i.\-e. the entropic penalty for producing a dimer from two monomers). The resulting free energies and pair probabilities are initially relative to that null model. In a second step the free energies can be corrected to include the dimerization penalty, and the pair probabilities can be divided into the conditional pair probabilities given that a re dimer is formed or not formed. See\cite{bernhart:2006} for further details.
  55
  56 \subsection{Function Documentation}
  57 \hypertarget{group__pf__cofold_gaa86a5f998789ed71813d23d7307a791b}{\index{Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}!co\-\_\-pf\-\_\-fold@{co\-\_\-pf\-\_\-fold}}
  58 \index{co\-\_\-pf\-\_\-fold@{co\-\_\-pf\-\_\-fold}!Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}}
  59 \subsubsection[{co\-\_\-pf\-\_\-fold}]{\setlength{\rightskip}{0pt plus 5cm}{\bf cofold\-F} co\-\_\-pf\-\_\-fold (
  60 \begin{DoxyParamCaption}
  61 \item[{char $\ast$}]{sequence, }
  62 \item[{char $\ast$}]{structure}
  63 \end{DoxyParamCaption}
  64 )}}\label{group__pf__cofold_gaa86a5f998789ed71813d23d7307a791b}
  65
  66
  67 Calculate partition function and base pair probabilities.
  68
  69 This is the cofold partition function folding. The second molecule starts at the \hyperlink{fold__vars_8h_ab9b2c3a37a5516614c06d0ab54b97cda}{cut\-\_\-point} nucleotide.
  70
  71 \begin{DoxyNote}{Note}
  72 Open\-M\-P\-: Since this function relies on the global parameters \hyperlink{fold__vars_8h_ad512b5dd4dbec60faccfe137bb474489}{do\-\_\-backtrack}, \hyperlink{fold__vars_8h_a72b511ed1201f7e23ec437e468790d74}{dangles}, \hyperlink{fold__vars_8h_ab4b11c8d9c758430960896bc3fe82ead}{temperature} and \hyperlink{fold__vars_8h_ad3b22044065acc6dee0af68931b52cfd}{pf\-\_\-scale} it is not threadsafe according to concurrent changes in these variables! Use \hyperlink{group__pf__cofold_gabd873b450832ab5f21101fc5ab354d21}{co\-\_\-pf\-\_\-fold\-\_\-par()} instead to circumvent this issue.
  73 \end{DoxyNote}
  74 \begin{DoxySeeAlso}{See Also}
  75 \hyperlink{group__pf__cofold_gabd873b450832ab5f21101fc5ab354d21}{co\-\_\-pf\-\_\-fold\-\_\-par()}
  76 \end{DoxySeeAlso}
  77
  78 \begin{DoxyParams}{Parameters}
  79 {\em sequence} & Concatenated R\-N\-A sequences \\
  80 \hline
  81 {\em structure} & Will hold the structure or constraints \\
  82 \hline
  83 \end{DoxyParams}
  84 \begin{DoxyReturn}{Returns}
  85 \hyperlink{structcofoldF}{cofold\-F} structure containing a set of energies needed for concentration computations.
  86 \end{DoxyReturn}
  87 \hypertarget{group__pf__cofold_gabd873b450832ab5f21101fc5ab354d21}{\index{Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}!co\-\_\-pf\-\_\-fold\-\_\-par@{co\-\_\-pf\-\_\-fold\-\_\-par}}
  88 \index{co\-\_\-pf\-\_\-fold\-\_\-par@{co\-\_\-pf\-\_\-fold\-\_\-par}!Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}}
  89 \subsubsection[{co\-\_\-pf\-\_\-fold\-\_\-par}]{\setlength{\rightskip}{0pt plus 5cm}{\bf cofold\-F} co\-\_\-pf\-\_\-fold\-\_\-par (
  90 \begin{DoxyParamCaption}
  91 \item[{char $\ast$}]{sequence, }
  92 \item[{char $\ast$}]{structure, }
  93 \item[{{\bf pf\-\_\-param\-T} $\ast$}]{parameters, }
  94 \item[{int}]{calculate\-\_\-bppm, }
  95 \item[{int}]{is\-\_\-constrained}
  96 \end{DoxyParamCaption}
  97 )}}\label{group__pf__cofold_gabd873b450832ab5f21101fc5ab354d21}
  98
  99
 100 Calculate partition function and base pair probabilities.
 101
 102 This is the cofold partition function folding. The second molecule starts at the \hyperlink{fold__vars_8h_ab9b2c3a37a5516614c06d0ab54b97cda}{cut\-\_\-point} nucleotide.
 103
 104 \begin{DoxySeeAlso}{See Also}
 105 \hyperlink{group__energy__parameters_ga6fc2f3eef5a3024d44963ac59a42e39d}{get\-\_\-boltzmann\-\_\-factors()}, \hyperlink{group__pf__cofold_gaa86a5f998789ed71813d23d7307a791b}{co\-\_\-pf\-\_\-fold()}
 106 \end{DoxySeeAlso}
 107
 108 \begin{DoxyParams}{Parameters}
 109 {\em sequence} & Concatenated R\-N\-A sequences \\
 110 \hline
 111 {\em structure} & Pointer to the structure constraint \\
 112 \hline
 113 {\em parameters} & Data structure containing the precalculated Boltzmann factors \\
 114 \hline
 115 {\em calculate\-\_\-bppm} & Switch to turn Base pair probability calculations on/off (0==off) \\
 116 \hline
 117 {\em is\-\_\-constrained} & Switch to indicate that a structure contraint is passed via the structure argument (0==off) \\
 118 \hline
 119 \end{DoxyParams}
 120 \begin{DoxyReturn}{Returns}
 121 \hyperlink{structcofoldF}{cofold\-F} structure containing a set of energies needed for concentration computations.
 122 \end{DoxyReturn}
 123 \hypertarget{group__pf__cofold_ga11f0252c1d2c4697253ff4b5bd392d3c}{\index{Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}!export\-\_\-co\-\_\-bppm@{export\-\_\-co\-\_\-bppm}}
 124 \index{export\-\_\-co\-\_\-bppm@{export\-\_\-co\-\_\-bppm}!Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}}
 125 \subsubsection[{export\-\_\-co\-\_\-bppm}]{\setlength{\rightskip}{0pt plus 5cm}double$\ast$ export\-\_\-co\-\_\-bppm (
 126 \begin{DoxyParamCaption}
 127 \item[{void}]{}
 128 \end{DoxyParamCaption}
 129 )}}\label{group__pf__cofold_ga11f0252c1d2c4697253ff4b5bd392d3c}
 130
 131
 132 Get a pointer to the base pair probability array.
 133
 134 Accessing the base pair probabilities for a pair (i,j) is achieved by \begin{DoxyVerb}FLT_OR_DBL *pr = export_bppm(); pr_ij = pr[iindx[i]-j]; \end{DoxyVerb}
 135
 136
 137 \begin{DoxySeeAlso}{See Also}
 138 \hyperlink{utils_8h_a55c0f6b3b07b6adf2ee235ba901fe397}{get\-\_\-iindx()}
 139 \end{DoxySeeAlso}
 140 \begin{DoxyReturn}{Returns}
 141 A pointer to the base pair probability array
 142 \end{DoxyReturn}
 143 \hypertarget{group__pf__cofold_ga6e0f36c1f9b7d9dd4bfbad914c1119e5}{\index{Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}!update\-\_\-co\-\_\-pf\-\_\-params@{update\-\_\-co\-\_\-pf\-\_\-params}}
 144 \index{update\-\_\-co\-\_\-pf\-\_\-params@{update\-\_\-co\-\_\-pf\-\_\-params}!Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}}
 145 \subsubsection[{update\-\_\-co\-\_\-pf\-\_\-params}]{\setlength{\rightskip}{0pt plus 5cm}void update\-\_\-co\-\_\-pf\-\_\-params (
 146 \begin{DoxyParamCaption}
 147 \item[{int}]{length}
 148 \end{DoxyParamCaption}
 149 )}}\label{group__pf__cofold_ga6e0f36c1f9b7d9dd4bfbad914c1119e5}
 150
 151
 152 Recalculate energy parameters.
 153
 154 This function recalculates all energy parameters given the current model settings.
 155
 156 \begin{DoxyNote}{Note}
 157 This function relies on the global variables \hyperlink{fold__vars_8h_ad3b22044065acc6dee0af68931b52cfd}{pf\-\_\-scale}, \hyperlink{fold__vars_8h_a72b511ed1201f7e23ec437e468790d74}{dangles} and \hyperlink{fold__vars_8h_ab4b11c8d9c758430960896bc3fe82ead}{temperature}. Thus it might not be threadsafe in certain situations. Use \hyperlink{group__pf__cofold_ga117d880df45bef444d5e2785ffa40a53}{update\-\_\-co\-\_\-pf\-\_\-params\-\_\-par()} instead.
 158 \end{DoxyNote}
 159 \begin{DoxySeeAlso}{See Also}
 160 \hyperlink{group__energy__parameters_ga6fc2f3eef5a3024d44963ac59a42e39d}{get\-\_\-boltzmann\-\_\-factors()}, \hyperlink{group__pf__cofold_ga117d880df45bef444d5e2785ffa40a53}{update\-\_\-co\-\_\-pf\-\_\-params\-\_\-par()}
 161 \end{DoxySeeAlso}
 162
 163 \begin{DoxyParams}{Parameters}
 164 {\em length} & Length of the current R\-N\-A sequence \\
 165 \hline
 166 \end{DoxyParams}
 167 \hypertarget{group__pf__cofold_ga117d880df45bef444d5e2785ffa40a53}{\index{Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}!update\-\_\-co\-\_\-pf\-\_\-params\-\_\-par@{update\-\_\-co\-\_\-pf\-\_\-params\-\_\-par}}
 168 \index{update\-\_\-co\-\_\-pf\-\_\-params\-\_\-par@{update\-\_\-co\-\_\-pf\-\_\-params\-\_\-par}!Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}}
 169 \subsubsection[{update\-\_\-co\-\_\-pf\-\_\-params\-\_\-par}]{\setlength{\rightskip}{0pt plus 5cm}void update\-\_\-co\-\_\-pf\-\_\-params\-\_\-par (
 170 \begin{DoxyParamCaption}
 171 \item[{int}]{length, }
 172 \item[{{\bf pf\-\_\-param\-T} $\ast$}]{parameters}
 173 \end{DoxyParamCaption}
 174 )}}\label{group__pf__cofold_ga117d880df45bef444d5e2785ffa40a53}
 175
 176
 177 Recalculate energy parameters.
 178
 179 This function recalculates all energy parameters given the current model settings. It's second argument can either be N\-U\-L\-L or a data structure containing the precomputed Boltzmann factors. In the first scenario, the necessary data structure will be created automatically according to the current global model settings, i.\-e. this mode might not be threadsafe. However, if the provided data structure is not N\-U\-L\-L, threadsafety for the model parameters \hyperlink{fold__vars_8h_a72b511ed1201f7e23ec437e468790d74}{dangles}, \hyperlink{fold__vars_8h_ad3b22044065acc6dee0af68931b52cfd}{pf\-\_\-scale} and \hyperlink{fold__vars_8h_ab4b11c8d9c758430960896bc3fe82ead}{temperature} is regained, since their values are taken from this data structure during subsequent calculations.
 180
 181 \begin{DoxySeeAlso}{See Also}
 182 \hyperlink{group__energy__parameters_ga6fc2f3eef5a3024d44963ac59a42e39d}{get\-\_\-boltzmann\-\_\-factors()}, \hyperlink{group__pf__cofold_ga6e0f36c1f9b7d9dd4bfbad914c1119e5}{update\-\_\-co\-\_\-pf\-\_\-params()}
 183 \end{DoxySeeAlso}
 184
 185 \begin{DoxyParams}{Parameters}
 186 {\em length} & Length of the current R\-N\-A sequence \\
 187 \hline
 188 {\em parameters} & data structure containing the precomputed Boltzmann factors \\
 189 \hline
 190 \end{DoxyParams}
 191 \hypertarget{group__pf__cofold_ga15ae04ac5ab84e876dcf0093120cb617}{\index{Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}!compute\-\_\-probabilities@{compute\-\_\-probabilities}}
 192 \index{compute\-\_\-probabilities@{compute\-\_\-probabilities}!Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}}
 193 \subsubsection[{compute\-\_\-probabilities}]{\setlength{\rightskip}{0pt plus 5cm}void compute\-\_\-probabilities (
 194 \begin{DoxyParamCaption}
 195 \item[{double}]{F\-A\-B, }
 196 \item[{double}]{F\-E\-A, }
 197 \item[{double}]{F\-E\-B, }
 198 \item[{struct {\bf plist} $\ast$}]{pr\-A\-B, }
 199 \item[{struct {\bf plist} $\ast$}]{pr\-A, }
 200 \item[{struct {\bf plist} $\ast$}]{pr\-B, }
 201 \item[{int}]{Alength}
 202 \end{DoxyParamCaption}
 203 )}}\label{group__pf__cofold_ga15ae04ac5ab84e876dcf0093120cb617}
 204
 205
 206 Compute Boltzmann probabilities of dimerization without homodimers.
 207
 208 Given the pair probabilities and free energies (in the null model) for a dimer A\-B and the two constituent monomers A and B, compute the conditional pair probabilities given that a dimer A\-B actually forms. Null model pair probabilities are given as a list as produced by \hyperlink{group__pf__fold_ga03e15e831a31b1154855ab47edbdb019}{assign\-\_\-plist\-\_\-from\-\_\-pr()}, the dimer probabilities 'pr\-A\-B' are modified in place.
 209
 210
 211 \begin{DoxyParams}{Parameters}
 212 {\em F\-A\-B} & free energy of dimer A\-B \\
 213 \hline
 214 {\em F\-E\-A} & free energy of monomer A \\
 215 \hline
 216 {\em F\-E\-B} & free energy of monomer B \\
 217 \hline
 218 {\em pr\-A\-B} & pair probabilities for dimer \\
 219 \hline
 220 {\em pr\-A} & pair probabilities monomer \\
 221 \hline
 222 {\em pr\-B} & pair probabilities monomer \\
 223 \hline
 224 {\em Alength} & Length of molecule A \\
 225 \hline
 226 \end{DoxyParams}
 227 \hypertarget{group__pf__cofold_ga5545cb936ac4ff93c7d699d46e72e8c7}{\index{Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}!get\-\_\-concentrations@{get\-\_\-concentrations}}
 228 \index{get\-\_\-concentrations@{get\-\_\-concentrations}!Partition Function for two hybridized Sequences@{Partition Function for two hybridized Sequences}}
 229 \subsubsection[{get\-\_\-concentrations}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Conc\-Ent}$\ast$ get\-\_\-concentrations (
 230 \begin{DoxyParamCaption}
 231 \item[{double}]{F\-E\-A\-B, }
 232 \item[{double}]{F\-E\-A\-A, }
 233 \item[{double}]{F\-E\-B\-B, }
 234 \item[{double}]{F\-E\-A, }
 235 \item[{double}]{F\-E\-B, }
 236 \item[{double $\ast$}]{startconc}
 237 \end{DoxyParamCaption}
 238 )}}\label{group__pf__cofold_ga5545cb936ac4ff93c7d699d46e72e8c7}
 239
 240
 241 Given two start monomer concentrations a and b, compute the concentrations in thermodynamic equilibrium of all dimers and the monomers.
 242
 243 This function takes an array 'startconc' of input concentrations with alternating entries for the initial concentrations of molecules A and B (terminated by two zeroes), then computes the resulting equilibrium concentrations from the free energies for the dimers. Dimer free energies should be the dimer-\/only free energies, i.\-e. the Fc\-A\-B entries from the \hyperlink{structcofoldF}{cofold\-F} struct.
 244
 245
 246 \begin{DoxyParams}{Parameters}
 247 {\em F\-E\-A\-B} & Free energy of A\-B dimer (Fc\-A\-B entry) \\
 248 \hline
 249 {\em F\-E\-A\-A} & Free energy of A\-A dimer (Fc\-A\-B entry) \\
 250 \hline
 251 {\em F\-E\-B\-B} & Free energy of B\-B dimer (Fc\-A\-B entry) \\
 252 \hline
 253 {\em F\-E\-A} & Free energy of monomer A \\
 254 \hline
 255 {\em F\-E\-B} & Free energy of monomer B \\
 256 \hline
 257 {\em startconc} & List of start concentrations \mbox{[}a0\mbox{]},\mbox{[}b0\mbox{]},\mbox{[}a1\mbox{]},\mbox{[}b1\mbox{]},...,\mbox{[}an\mbox{]}\mbox{[}bn\mbox{]},\mbox{[}0\mbox{]},\mbox{[}0\mbox{]} \\
 258 \hline
 259 \end{DoxyParams}
 260 \begin{DoxyReturn}{Returns}
 261 \hyperlink{structConcEnt}{Conc\-Ent} array containing the equilibrium energies and start concentrations
 262 \end{DoxyReturn}