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

   1 \hypertarget{group__mfe__fold}{\section{Calculating Minimum Free Energy (M\-F\-E) Structures}
   2 \label{group__mfe__fold}\index{Calculating Minimum Free Energy (\-M\-F\-E) Structures@{Calculating Minimum Free Energy (\-M\-F\-E) Structures}}
   3 }
   4
   5
   6 This module contains all functions and variables related to the calculation of global minimum free energy structures for single sequences.
   7
   8
   9 Collaboration diagram for Calculating Minimum Free Energy (M\-F\-E) Structures\-:
  10 \nopagebreak
  11 \begin{figure}[H]
  12 \begin{center}
  13 \leavevmode
  14 \includegraphics[width=350pt]{group__mfe__fold}
  15 \end{center}
  16 \end{figure}
  17 \subsection*{Modules}
  18 \begin{DoxyCompactItemize}
  19 \item
  20 \hyperlink{group__mfe__cofold}{M\-F\-E Structures of two hybridized Sequences}
  21 \item
  22 \hyperlink{group__consensus__mfe__fold}{M\-F\-E Consensus Structures for Sequence Alignment(s)}
  23 \item
  24 \hyperlink{group__local__mfe__fold}{Local M\-F\-E structure Prediction and Z-\/scores}
  25 \item
  26 \hyperlink{group__kl__neighborhood__mfe}{Calculating M\-F\-E representatives of a Distance Based Partitioning}
  27 \begin{DoxyCompactList}\small\item\em Compute the minimum free energy (M\-F\-E) and secondary structures for a partitioning of the secondary structure space according to the base pair distance to two fixed reference structures basepair distance to two fixed reference structures. \end{DoxyCompactList}\end{DoxyCompactItemize}
  28 \subsection*{Functions}
  29 \begin{DoxyCompactItemize}
  30 \item
  31 float \hyperlink{group__mfe__fold_gadb973133c241d57c04b253df35e4d34e}{fold\-\_\-par} (const char $\ast$sequence, char $\ast$structure, \hyperlink{structparamT}{param\-T} $\ast$parameters, int is\-\_\-constrained, int is\-\_\-circular)
  32 \begin{DoxyCompactList}\small\item\em Compute minimum free energy and an appropriate secondary structure of an R\-N\-A sequence. \end{DoxyCompactList}\item
  33 float \hyperlink{group__mfe__fold_gaadafcb0f140795ae62e5ca027e335a9b}{fold} (const char $\ast$sequence, char $\ast$structure)
  34 \begin{DoxyCompactList}\small\item\em Compute minimum free energy and an appropriate secondary structure of an R\-N\-A sequence. \end{DoxyCompactList}\item
  35 float \hyperlink{group__mfe__fold_ga4ac63ab3e8d9a80ced28b8052d94e423}{circfold} (const char $\ast$sequence, char $\ast$structure)
  36 \begin{DoxyCompactList}\small\item\em Compute minimum free energy and an appropriate secondary structure of a circular R\-N\-A sequence. \end{DoxyCompactList}\item
  37 \hypertarget{group__mfe__fold_ga107fdfe5fd641868156bfd849f6866c7}{void \hyperlink{group__mfe__fold_ga107fdfe5fd641868156bfd849f6866c7}{free\-\_\-arrays} (void)}\label{group__mfe__fold_ga107fdfe5fd641868156bfd849f6866c7}
  38
  39 \begin{DoxyCompactList}\small\item\em Free arrays for mfe folding. \end{DoxyCompactList}\item
  40 \hypertarget{group__mfe__fold_ga41bf8f6fa15b94471f7095cad9f0ccf3}{void \hyperlink{group__mfe__fold_ga41bf8f6fa15b94471f7095cad9f0ccf3}{update\-\_\-fold\-\_\-params} (void)}\label{group__mfe__fold_ga41bf8f6fa15b94471f7095cad9f0ccf3}
  41
  42 \begin{DoxyCompactList}\small\item\em Recalculate energy parameters. \end{DoxyCompactList}\end{DoxyCompactItemize}
  43
  44
  45 \subsection{Detailed Description}
  46 This module contains all functions and variables related to the calculation of global minimum free energy structures for single sequences. This section covers all functions and variables related to the calculation of minimum free energy (M\-F\-E) structures.
  47
  48 The library provides a fast dynamic programming minimum free energy folding algorithm as described by Zuker \& Stiegler (1981).
  49
  50 The library provides a fast dynamic programming minimum free energy folding algorithm as described in\cite{zuker:1981}. All relevant parts that directly implement the \char`\"{}\-Zuker \& Stiegler\char`\"{} algorithm for single sequences are described in this section.
  51
  52 Folding of circular R\-N\-A sequences is handled as a post-\/processing step of the forward recursions. See\cite{hofacker:2006} for further details.
  53
  54 Nevertheless, the R\-N\-Alib also provides interfaces for the prediction of consensus M\-F\-E structures of sequence alignments, M\-F\-E structure for two hybridized sequences, local optimal structures and many more. For those more specialized variants of M\-F\-E folding routines, please consult the appropriate subsections (Modules) as listed above.
  55
  56 \subsection{Function Documentation}
  57 \hypertarget{group__mfe__fold_gadb973133c241d57c04b253df35e4d34e}{\index{Calculating Minimum Free Energy (\-M\-F\-E) Structures@{Calculating Minimum Free Energy (\-M\-F\-E) Structures}!fold\-\_\-par@{fold\-\_\-par}}
  58 \index{fold\-\_\-par@{fold\-\_\-par}!Calculating Minimum Free Energy (MFE) Structures@{Calculating Minimum Free Energy (\-M\-F\-E) Structures}}
  59 \subsubsection[{fold\-\_\-par}]{\setlength{\rightskip}{0pt plus 5cm}float fold\-\_\-par (
  60 \begin{DoxyParamCaption}
  61 \item[{const char $\ast$}]{sequence, }
  62 \item[{char $\ast$}]{structure, }
  63 \item[{{\bf param\-T} $\ast$}]{parameters, }
  64 \item[{int}]{is\-\_\-constrained, }
  65 \item[{int}]{is\-\_\-circular}
  66 \end{DoxyParamCaption}
  67 )}}\label{group__mfe__fold_gadb973133c241d57c04b253df35e4d34e}
  68
  69
  70 Compute minimum free energy and an appropriate secondary structure of an R\-N\-A sequence.
  71
  72 The first parameter given, the R\-N\-A sequence, must be {\itshape uppercase} and should only contain an alphabet $\Sigma$ that is understood by the R\-N\-Alib\par
  73  (e.\-g. $ \Sigma = \{A,U,C,G\} $)\par
  74
  75
  76 The second parameter, {\itshape structure}, must always point to an allocated block of memory with a size of at least $\mathrm{strlen}(\mathrm{sequence})+1$
  77
  78 If the third parameter is N\-U\-L\-L, global model detail settings are assumed for the folding recursions. Otherwise, the provided parameters are used.
  79
  80 The fourth parameter indicates whether a secondary structure constraint in enhanced dot-\/bracket notation is passed through the structure parameter or not. If so, the characters \char`\"{} $|$ x $<$ $>$ \char`\"{} are recognized to mark bases that are paired, unpaired, paired upstream, or downstream, respectively. Matching brackets \char`\"{} ( ) \char`\"{} denote base pairs, dots \char`\"{}.\char`\"{} are used for unconstrained bases.
  81
  82 To indicate that the R\-N\-A sequence is circular and thus has to be post-\/processed, set the last parameter to non-\/zero
  83
  84 After a successful call of \hyperlink{group__mfe__fold_gadb973133c241d57c04b253df35e4d34e}{fold\-\_\-par()}, a backtracked secondary structure (in dot-\/bracket notation) that exhibits the minimum of free energy will be written to the memory {\itshape structure} is pointing to. The function returns the minimum of free energy for any fold of the sequence given.
  85
  86 \begin{DoxyNote}{Note}
  87 Open\-M\-P\-: Passing N\-U\-L\-L to the 'parameters' argument involves access to several global model detail variables and thus is not to be considered threadsafe
  88 \end{DoxyNote}
  89 \begin{DoxySeeAlso}{See Also}
  90 \hyperlink{group__mfe__fold_gaadafcb0f140795ae62e5ca027e335a9b}{fold()}, \hyperlink{group__mfe__fold_ga4ac63ab3e8d9a80ced28b8052d94e423}{circfold()}, \hyperlink{structmodel__detailsT}{model\-\_\-details\-T}, set\-\_\-energy\-\_\-model(), \hyperlink{group__energy__parameters_gac2f3ca440b7eaf4d999fb27da949fe72}{get\-\_\-scaled\-\_\-parameters()}
  91 \end{DoxySeeAlso}
  92
  93 \begin{DoxyParams}{Parameters}
  94 {\em sequence} & R\-N\-A sequence \\
  95 \hline
  96 {\em structure} & A pointer to the character array where the secondary structure in dot-\/bracket notation will be written to \\
  97 \hline
  98 {\em parameters} & A data structure containing the prescaled energy contributions and the model details. (N\-U\-L\-L may be passed, see Open\-M\-P notes above) \\
  99 \hline
 100 {\em is\-\_\-constrained} & Switch to indicate that a structure contraint is passed via the structure argument (0==off) \\
 101 \hline
 102 {\em is\-\_\-circular} & Switch to (de-\/)activate postprocessing steps in case R\-N\-A sequence is circular (0==off)\\
 103 \hline
 104 \end{DoxyParams}
 105 \begin{DoxyReturn}{Returns}
 106 the minimum free energy (M\-F\-E) in kcal/mol
 107 \end{DoxyReturn}
 108 \hypertarget{group__mfe__fold_gaadafcb0f140795ae62e5ca027e335a9b}{\index{Calculating Minimum Free Energy (\-M\-F\-E) Structures@{Calculating Minimum Free Energy (\-M\-F\-E) Structures}!fold@{fold}}
 109 \index{fold@{fold}!Calculating Minimum Free Energy (MFE) Structures@{Calculating Minimum Free Energy (\-M\-F\-E) Structures}}
 110 \subsubsection[{fold}]{\setlength{\rightskip}{0pt plus 5cm}float fold (
 111 \begin{DoxyParamCaption}
 112 \item[{const char $\ast$}]{sequence, }
 113 \item[{char $\ast$}]{structure}
 114 \end{DoxyParamCaption}
 115 )}}\label{group__mfe__fold_gaadafcb0f140795ae62e5ca027e335a9b}
 116
 117
 118 Compute minimum free energy and an appropriate secondary structure of an R\-N\-A sequence.
 119
 120 This function essentially does the same thing as \hyperlink{group__mfe__fold_gadb973133c241d57c04b253df35e4d34e}{fold\-\_\-par()}. However, it takes its model details, i.\-e. \hyperlink{fold__vars_8h_ab4b11c8d9c758430960896bc3fe82ead}{temperature}, \hyperlink{fold__vars_8h_a72b511ed1201f7e23ec437e468790d74}{dangles}, \hyperlink{fold__vars_8h_a4f6265bdf0ead7ff4628a360adbfd77e}{tetra\-\_\-loop}, \hyperlink{fold__vars_8h_abf380d09e4f1ab94fc6af57cf0ad5d32}{no\-G\-U}, \hyperlink{fold__vars_8h_aa8d1c7b92489179e1eafa562b7bdd259}{no\-\_\-closing\-G\-U}, \hyperlink{fold__vars_8h_a0afc287c2464866d94858c39175154af}{fold\-\_\-constrained}, \hyperlink{fold__vars_8h_a097eccaabd6ae8b4fef83cccff85bb5d}{no\-Lonely\-Pairs} from the current global settings within the library
 121
 122 Use \hyperlink{group__mfe__fold_gadb973133c241d57c04b253df35e4d34e}{fold\-\_\-par()} for a completely threadsafe variant
 123
 124 \begin{DoxySeeAlso}{See Also}
 125 \hyperlink{group__mfe__fold_gadb973133c241d57c04b253df35e4d34e}{fold\-\_\-par()}, \hyperlink{group__mfe__fold_ga4ac63ab3e8d9a80ced28b8052d94e423}{circfold()}
 126 \end{DoxySeeAlso}
 127
 128 \begin{DoxyParams}{Parameters}
 129 {\em sequence} & R\-N\-A sequence \\
 130 \hline
 131 {\em structure} & A pointer to the character array where the secondary structure in dot-\/bracket notation will be written to \\
 132 \hline
 133 \end{DoxyParams}
 134 \begin{DoxyReturn}{Returns}
 135 the minimum free energy (M\-F\-E) in kcal/mol
 136 \end{DoxyReturn}
 137 \hypertarget{group__mfe__fold_ga4ac63ab3e8d9a80ced28b8052d94e423}{\index{Calculating Minimum Free Energy (\-M\-F\-E) Structures@{Calculating Minimum Free Energy (\-M\-F\-E) Structures}!circfold@{circfold}}
 138 \index{circfold@{circfold}!Calculating Minimum Free Energy (MFE) Structures@{Calculating Minimum Free Energy (\-M\-F\-E) Structures}}
 139 \subsubsection[{circfold}]{\setlength{\rightskip}{0pt plus 5cm}float circfold (
 140 \begin{DoxyParamCaption}
 141 \item[{const char $\ast$}]{sequence, }
 142 \item[{char $\ast$}]{structure}
 143 \end{DoxyParamCaption}
 144 )}}\label{group__mfe__fold_ga4ac63ab3e8d9a80ced28b8052d94e423}
 145
 146
 147 Compute minimum free energy and an appropriate secondary structure of a circular R\-N\-A sequence.
 148
 149 This function essentially does the same thing as \hyperlink{group__mfe__fold_gadb973133c241d57c04b253df35e4d34e}{fold\-\_\-par()}. However, it takes its model details, i.\-e. \hyperlink{fold__vars_8h_ab4b11c8d9c758430960896bc3fe82ead}{temperature}, \hyperlink{fold__vars_8h_a72b511ed1201f7e23ec437e468790d74}{dangles}, \hyperlink{fold__vars_8h_a4f6265bdf0ead7ff4628a360adbfd77e}{tetra\-\_\-loop}, \hyperlink{fold__vars_8h_abf380d09e4f1ab94fc6af57cf0ad5d32}{no\-G\-U}, \hyperlink{fold__vars_8h_aa8d1c7b92489179e1eafa562b7bdd259}{no\-\_\-closing\-G\-U}, \hyperlink{fold__vars_8h_a0afc287c2464866d94858c39175154af}{fold\-\_\-constrained}, \hyperlink{fold__vars_8h_a097eccaabd6ae8b4fef83cccff85bb5d}{no\-Lonely\-Pairs} from the current global settings within the library
 150
 151 Use \hyperlink{group__mfe__fold_gadb973133c241d57c04b253df35e4d34e}{fold\-\_\-par()} for a completely threadsafe variant
 152
 153 \begin{DoxySeeAlso}{See Also}
 154 \hyperlink{group__mfe__fold_gadb973133c241d57c04b253df35e4d34e}{fold\-\_\-par()}, \hyperlink{group__mfe__fold_ga4ac63ab3e8d9a80ced28b8052d94e423}{circfold()}
 155 \end{DoxySeeAlso}
 156
 157 \begin{DoxyParams}{Parameters}
 158 {\em sequence} & R\-N\-A sequence \\
 159 \hline
 160 {\em structure} & A pointer to the character array where the secondary structure in dot-\/bracket notation will be written to \\
 161 \hline
 162 \end{DoxyParams}
 163 \begin{DoxyReturn}{Returns}
 164 the minimum free energy (M\-F\-E) in kcal/mol
 165 \end{DoxyReturn}