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

   1 \hypertarget{group__consensus__fold}{\section{Predicting Consensus Structures from Alignment(s)}
   2 \label{group__consensus__fold}\index{Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}}
   3 }
   4
   5
   6 compute various properties (consensus M\-F\-E structures, partition function, Boltzmann distributed stochastic samples, ...) for R\-N\-A sequence alignments
   7
   8
   9 Collaboration diagram for Predicting Consensus Structures from Alignment(s)\-:
  10 \nopagebreak
  11 \begin{figure}[H]
  12 \begin{center}
  13 \leavevmode
  14 \includegraphics[width=350pt]{group__consensus__fold}
  15 \end{center}
  16 \end{figure}
  17 \subsection*{Modules}
  18 \begin{DoxyCompactItemize}
  19 \item
  20 \hyperlink{group__consensus__mfe__fold}{M\-F\-E Consensus Structures for Sequence Alignment(s)}
  21 \item
  22 \hyperlink{group__consensus__pf__fold}{Partition Function and Base Pair Probabilities for Sequence Alignment(s)}
  23 \item
  24 \hyperlink{group__consensus__stochbt}{Stochastic Backtracking of Consensus Structures from Sequence Alignment(s)}
  25 \item
  26 \hyperlink{group__local__consensus__fold}{Local M\-F\-E consensus structures for Sequence Alignments}
  27 \end{DoxyCompactItemize}
  28 \subsection*{Files}
  29 \begin{DoxyCompactItemize}
  30 \item
  31 file \hyperlink{alifold_8h}{alifold.\-h}
  32 \begin{DoxyCompactList}\small\item\em compute various properties (consensus M\-F\-E structures, partition function, Boltzmann distributed stochastic samples, ...) for R\-N\-A sequence alignments \end{DoxyCompactList}\end{DoxyCompactItemize}
  33 \subsection*{Functions}
  34 \begin{DoxyCompactItemize}
  35 \item
  36 int \hyperlink{group__consensus__fold_gaa2d600be90844094ec145ea14a314d2f}{get\-\_\-mpi} (char $\ast$Alseq\mbox{[}$\,$\mbox{]}, int n\-\_\-seq, int length, int $\ast$mini)
  37 \begin{DoxyCompactList}\small\item\em Get the mean pairwise identity in steps from ?to?(ident) \end{DoxyCompactList}\item
  38 \hypertarget{group__consensus__fold_ga5e125c9586fcd4e2e1559fe76f7289cc}{float $\ast$$\ast$ \hyperlink{group__consensus__fold_ga5e125c9586fcd4e2e1559fe76f7289cc}{readribosum} (char $\ast$name)}\label{group__consensus__fold_ga5e125c9586fcd4e2e1559fe76f7289cc}
  39
  40 \begin{DoxyCompactList}\small\item\em Read a ribosum or other user-\/defined scoring matrix. \end{DoxyCompactList}\item
  41 float \hyperlink{group__consensus__fold_ga1c48869c03b49a342bf4cbdd61900081}{energy\-\_\-of\-\_\-alistruct} (const char $\ast$$\ast$sequences, const char $\ast$structure, int n\-\_\-seq, float $\ast$energy)
  42 \begin{DoxyCompactList}\small\item\em Calculate the free energy of a consensus structure given a set of aligned sequences. \end{DoxyCompactList}\item
  43 void \hyperlink{group__consensus__fold_gaa3e40277c837d6f7603afe319884c786}{encode\-\_\-ali\-\_\-sequence} (const char $\ast$sequence, short $\ast$S, short $\ast$s5, short $\ast$s3, char $\ast$ss, unsigned short $\ast$as, int \hyperlink{fold__vars_8h_af9202a1a09f5828dc731e2d9a10fa111}{circ})
  44 \begin{DoxyCompactList}\small\item\em Get arrays with encoded sequence of the alignment. \end{DoxyCompactList}\item
  45 void \hyperlink{group__consensus__fold_ga8a560930f7f2582cc3967723a86cfdfa}{alloc\-\_\-sequence\-\_\-arrays} (const char $\ast$$\ast$sequences, short $\ast$$\ast$$\ast$S, short $\ast$$\ast$$\ast$S5, short $\ast$$\ast$$\ast$S3, unsigned short $\ast$$\ast$$\ast$a2s, char $\ast$$\ast$$\ast$Ss, int \hyperlink{fold__vars_8h_af9202a1a09f5828dc731e2d9a10fa111}{circ})
  46 \begin{DoxyCompactList}\small\item\em Allocate memory for sequence array used to deal with aligned sequences. \end{DoxyCompactList}\item
  47 void \hyperlink{group__consensus__fold_ga298a420a8c879202e2617b3f724fde38}{free\-\_\-sequence\-\_\-arrays} (unsigned int n\-\_\-seq, short $\ast$$\ast$$\ast$S, short $\ast$$\ast$$\ast$S5, short $\ast$$\ast$$\ast$S3, unsigned short $\ast$$\ast$$\ast$a2s, char $\ast$$\ast$$\ast$Ss)
  48 \begin{DoxyCompactList}\small\item\em Free the memory of the sequence arrays used to deal with aligned sequences. \end{DoxyCompactList}\item
  49 int \hyperlink{group__consensus__fold_ga0cc49457fd79eeb04d4a7f97c868b09b}{get\-\_\-alipf\-\_\-arrays} (short $\ast$$\ast$$\ast$S\-\_\-p, short $\ast$$\ast$$\ast$S5\-\_\-p, short $\ast$$\ast$$\ast$S3\-\_\-p, unsigned short $\ast$$\ast$$\ast$a2s\-\_\-p, char $\ast$$\ast$$\ast$Ss\-\_\-p, double $\ast$$\ast$qb\-\_\-p, double $\ast$$\ast$qm\-\_\-p, double $\ast$$\ast$q1k\-\_\-p, double $\ast$$\ast$qln\-\_\-p, short $\ast$$\ast$pscore)
  50 \begin{DoxyCompactList}\small\item\em Get pointers to (almost) all relavant arrays used in alifold's partition function computation. \end{DoxyCompactList}\end{DoxyCompactItemize}
  51 \subsection*{Variables}
  52 \begin{DoxyCompactItemize}
  53 \item
  54 double \hyperlink{group__consensus__fold_gaf3cbac6ff5d706d6e414677841ddf94c}{cv\-\_\-fact}
  55 \begin{DoxyCompactList}\small\item\em This variable controls the weight of the covariance term in the energy function of alignment folding algorithms. \end{DoxyCompactList}\item
  56 double \hyperlink{group__consensus__fold_ga502948a122a2af5b914355b1f3ea2f61}{nc\-\_\-fact}
  57 \begin{DoxyCompactList}\small\item\em This variable controls the magnitude of the penalty for non-\/compatible sequences in the covariance term of alignment folding algorithms. \end{DoxyCompactList}\end{DoxyCompactItemize}
  58
  59
  60 \subsection{Detailed Description}
  61 compute various properties (consensus M\-F\-E structures, partition function, Boltzmann distributed stochastic samples, ...) for R\-N\-A sequence alignments Consensus structures can be predicted by a modified version of the \hyperlink{group__mfe__fold_gaadafcb0f140795ae62e5ca027e335a9b}{fold()} algorithm that takes a set of aligned sequences instead of a single sequence. The energy function consists of the mean energy averaged over the sequences, plus a covariance term that favors pairs with consistent and compensatory mutations and penalizes pairs that cannot be formed by all structures. For details see\cite{hofacker:2002} and \cite{bernhart:2008}.
  62
  63 \subsection{Function Documentation}
  64 \hypertarget{group__consensus__fold_gaa2d600be90844094ec145ea14a314d2f}{\index{Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}!get\-\_\-mpi@{get\-\_\-mpi}}
  65 \index{get\-\_\-mpi@{get\-\_\-mpi}!Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}}
  66 \subsubsection[{get\-\_\-mpi}]{\setlength{\rightskip}{0pt plus 5cm}int get\-\_\-mpi (
  67 \begin{DoxyParamCaption}
  68 \item[{char $\ast$}]{Alseq\mbox{[}$\,$\mbox{]}, }
  69 \item[{int}]{n\-\_\-seq, }
  70 \item[{int}]{length, }
  71 \item[{int $\ast$}]{mini}
  72 \end{DoxyParamCaption}
  73 )}}\label{group__consensus__fold_gaa2d600be90844094ec145ea14a314d2f}
  74
  75
  76 Get the mean pairwise identity in steps from ?to?(ident)
  77
  78
  79 \begin{DoxyParams}{Parameters}
  80 {\em Alseq} & \\
  81 \hline
  82 {\em n\-\_\-seq} & The number of sequences in the alignment \\
  83 \hline
  84 {\em length} & The length of the alignment \\
  85 \hline
  86 {\em mini} & \\
  87 \hline
  88 \end{DoxyParams}
  89 \begin{DoxyReturn}{Returns}
  90 The mean pairwise identity
  91 \end{DoxyReturn}
  92 \hypertarget{group__consensus__fold_ga1c48869c03b49a342bf4cbdd61900081}{\index{Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}!energy\-\_\-of\-\_\-alistruct@{energy\-\_\-of\-\_\-alistruct}}
  93 \index{energy\-\_\-of\-\_\-alistruct@{energy\-\_\-of\-\_\-alistruct}!Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}}
  94 \subsubsection[{energy\-\_\-of\-\_\-alistruct}]{\setlength{\rightskip}{0pt plus 5cm}float energy\-\_\-of\-\_\-alistruct (
  95 \begin{DoxyParamCaption}
  96 \item[{const char $\ast$$\ast$}]{sequences, }
  97 \item[{const char $\ast$}]{structure, }
  98 \item[{int}]{n\-\_\-seq, }
  99 \item[{float $\ast$}]{energy}
 100 \end{DoxyParamCaption}
 101 )}}\label{group__consensus__fold_ga1c48869c03b49a342bf4cbdd61900081}
 102
 103
 104 Calculate the free energy of a consensus structure given a set of aligned sequences.
 105
 106
 107 \begin{DoxyParams}{Parameters}
 108 {\em sequences} & The N\-U\-L\-L terminated array of sequences \\
 109 \hline
 110 {\em structure} & The consensus structure \\
 111 \hline
 112 {\em n\-\_\-seq} & The number of sequences in the alignment \\
 113 \hline
 114 {\em energy} & A pointer to an array of at least two floats that will hold the free energies (energy\mbox{[}0\mbox{]} will contain the free energy, energy\mbox{[}1\mbox{]} will be filled with the covariance energy term) \\
 115 \hline
 116 \end{DoxyParams}
 117 \begin{DoxyReturn}{Returns}
 118 free energy in kcal/mol
 119 \end{DoxyReturn}
 120 \hypertarget{group__consensus__fold_gaa3e40277c837d6f7603afe319884c786}{\index{Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}!encode\-\_\-ali\-\_\-sequence@{encode\-\_\-ali\-\_\-sequence}}
 121 \index{encode\-\_\-ali\-\_\-sequence@{encode\-\_\-ali\-\_\-sequence}!Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}}
 122 \subsubsection[{encode\-\_\-ali\-\_\-sequence}]{\setlength{\rightskip}{0pt plus 5cm}void encode\-\_\-ali\-\_\-sequence (
 123 \begin{DoxyParamCaption}
 124 \item[{const char $\ast$}]{sequence, }
 125 \item[{short $\ast$}]{S, }
 126 \item[{short $\ast$}]{s5, }
 127 \item[{short $\ast$}]{s3, }
 128 \item[{char $\ast$}]{ss, }
 129 \item[{unsigned short $\ast$}]{as, }
 130 \item[{int}]{circ}
 131 \end{DoxyParamCaption}
 132 )}}\label{group__consensus__fold_gaa3e40277c837d6f7603afe319884c786}
 133
 134
 135 Get arrays with encoded sequence of the alignment.
 136
 137 this function assumes that in S, S5, s3, ss and as enough space is already allocated (size must be at least sequence length+2)
 138
 139
 140 \begin{DoxyParams}{Parameters}
 141 {\em sequence} & The gapped sequence from the alignment \\
 142 \hline
 143 {\em S} & pointer to an array that holds encoded sequence \\
 144 \hline
 145 {\em s5} & pointer to an array that holds the next base 5' of alignment position i \\
 146 \hline
 147 {\em s3} & pointer to an array that holds the next base 3' of alignment position i \\
 148 \hline
 149 {\em ss} & \\
 150 \hline
 151 {\em as} & \\
 152 \hline
 153 {\em circ} & assume the molecules to be circular instead of linear (circ=0) \\
 154 \hline
 155 \end{DoxyParams}
 156 \hypertarget{group__consensus__fold_ga8a560930f7f2582cc3967723a86cfdfa}{\index{Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}!alloc\-\_\-sequence\-\_\-arrays@{alloc\-\_\-sequence\-\_\-arrays}}
 157 \index{alloc\-\_\-sequence\-\_\-arrays@{alloc\-\_\-sequence\-\_\-arrays}!Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}}
 158 \subsubsection[{alloc\-\_\-sequence\-\_\-arrays}]{\setlength{\rightskip}{0pt plus 5cm}void alloc\-\_\-sequence\-\_\-arrays (
 159 \begin{DoxyParamCaption}
 160 \item[{const char $\ast$$\ast$}]{sequences, }
 161 \item[{short $\ast$$\ast$$\ast$}]{S, }
 162 \item[{short $\ast$$\ast$$\ast$}]{S5, }
 163 \item[{short $\ast$$\ast$$\ast$}]{S3, }
 164 \item[{unsigned short $\ast$$\ast$$\ast$}]{a2s, }
 165 \item[{char $\ast$$\ast$$\ast$}]{Ss, }
 166 \item[{int}]{circ}
 167 \end{DoxyParamCaption}
 168 )}}\label{group__consensus__fold_ga8a560930f7f2582cc3967723a86cfdfa}
 169
 170
 171 Allocate memory for sequence array used to deal with aligned sequences.
 172
 173 Note that these arrays will also be initialized according to the sequence alignment given
 174
 175 \begin{DoxySeeAlso}{See Also}
 176 \hyperlink{group__consensus__fold_ga298a420a8c879202e2617b3f724fde38}{free\-\_\-sequence\-\_\-arrays()}
 177 \end{DoxySeeAlso}
 178
 179 \begin{DoxyParams}{Parameters}
 180 {\em sequences} & The aligned sequences \\
 181 \hline
 182 {\em S} & A pointer to the array of encoded sequences \\
 183 \hline
 184 {\em S5} & A pointer to the array that contains the next 5' nucleotide of a sequence position \\
 185 \hline
 186 {\em S3} & A pointer to the array that contains the next 3' nucleotide of a sequence position \\
 187 \hline
 188 {\em a2s} & A pointer to the array that contains the alignment to sequence position mapping \\
 189 \hline
 190 {\em Ss} & A pointer to the array that contains the ungapped sequence \\
 191 \hline
 192 {\em circ} & assume the molecules to be circular instead of linear (circ=0) \\
 193 \hline
 194 \end{DoxyParams}
 195 \hypertarget{group__consensus__fold_ga298a420a8c879202e2617b3f724fde38}{\index{Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}!free\-\_\-sequence\-\_\-arrays@{free\-\_\-sequence\-\_\-arrays}}
 196 \index{free\-\_\-sequence\-\_\-arrays@{free\-\_\-sequence\-\_\-arrays}!Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}}
 197 \subsubsection[{free\-\_\-sequence\-\_\-arrays}]{\setlength{\rightskip}{0pt plus 5cm}void free\-\_\-sequence\-\_\-arrays (
 198 \begin{DoxyParamCaption}
 199 \item[{unsigned int}]{n\-\_\-seq, }
 200 \item[{short $\ast$$\ast$$\ast$}]{S, }
 201 \item[{short $\ast$$\ast$$\ast$}]{S5, }
 202 \item[{short $\ast$$\ast$$\ast$}]{S3, }
 203 \item[{unsigned short $\ast$$\ast$$\ast$}]{a2s, }
 204 \item[{char $\ast$$\ast$$\ast$}]{Ss}
 205 \end{DoxyParamCaption}
 206 )}}\label{group__consensus__fold_ga298a420a8c879202e2617b3f724fde38}
 207
 208
 209 Free the memory of the sequence arrays used to deal with aligned sequences.
 210
 211 This function frees the memory previously allocated with \hyperlink{group__consensus__fold_ga8a560930f7f2582cc3967723a86cfdfa}{alloc\-\_\-sequence\-\_\-arrays()}
 212
 213 \begin{DoxySeeAlso}{See Also}
 214 \hyperlink{group__consensus__fold_ga8a560930f7f2582cc3967723a86cfdfa}{alloc\-\_\-sequence\-\_\-arrays()}
 215 \end{DoxySeeAlso}
 216
 217 \begin{DoxyParams}{Parameters}
 218 {\em n\-\_\-seq} & The number of aligned sequences \\
 219 \hline
 220 {\em S} & A pointer to the array of encoded sequences \\
 221 \hline
 222 {\em S5} & A pointer to the array that contains the next 5' nucleotide of a sequence position \\
 223 \hline
 224 {\em S3} & A pointer to the array that contains the next 3' nucleotide of a sequence position \\
 225 \hline
 226 {\em a2s} & A pointer to the array that contains the alignment to sequence position mapping \\
 227 \hline
 228 {\em Ss} & A pointer to the array that contains the ungapped sequence \\
 229 \hline
 230 \end{DoxyParams}
 231 \hypertarget{group__consensus__fold_ga0cc49457fd79eeb04d4a7f97c868b09b}{\index{Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}!get\-\_\-alipf\-\_\-arrays@{get\-\_\-alipf\-\_\-arrays}}
 232 \index{get\-\_\-alipf\-\_\-arrays@{get\-\_\-alipf\-\_\-arrays}!Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}}
 233 \subsubsection[{get\-\_\-alipf\-\_\-arrays}]{\setlength{\rightskip}{0pt plus 5cm}int get\-\_\-alipf\-\_\-arrays (
 234 \begin{DoxyParamCaption}
 235 \item[{short $\ast$$\ast$$\ast$}]{S\-\_\-p, }
 236 \item[{short $\ast$$\ast$$\ast$}]{S5\-\_\-p, }
 237 \item[{short $\ast$$\ast$$\ast$}]{S3\-\_\-p, }
 238 \item[{unsigned short $\ast$$\ast$$\ast$}]{a2s\-\_\-p, }
 239 \item[{char $\ast$$\ast$$\ast$}]{Ss\-\_\-p, }
 240 \item[{double $\ast$$\ast$}]{qb\-\_\-p, }
 241 \item[{double $\ast$$\ast$}]{qm\-\_\-p, }
 242 \item[{double $\ast$$\ast$}]{q1k\-\_\-p, }
 243 \item[{double $\ast$$\ast$}]{qln\-\_\-p, }
 244 \item[{short $\ast$$\ast$}]{pscore}
 245 \end{DoxyParamCaption}
 246 )}}\label{group__consensus__fold_ga0cc49457fd79eeb04d4a7f97c868b09b}
 247
 248
 249 Get pointers to (almost) all relavant arrays used in alifold's partition function computation.
 250
 251 \begin{DoxyNote}{Note}
 252 To obtain meaningful pointers, call alipf\-\_\-fold first!
 253 \end{DoxyNote}
 254 \begin{DoxySeeAlso}{See Also}
 255 pf\-\_\-alifold(), \hyperlink{group__consensus__pf__fold_ga6b4dde1d43b79ab3753508c46cf50363}{alipf\-\_\-circ\-\_\-fold()}
 256 \end{DoxySeeAlso}
 257
 258 \begin{DoxyParams}{Parameters}
 259 {\em S\-\_\-p} & A pointer to the 'S' array (integer representation of nucleotides) \\
 260 \hline
 261 {\em S5\-\_\-p} & A pointer to the 'S5' array \\
 262 \hline
 263 {\em S3\-\_\-p} & A pointer to the 'S3' array \\
 264 \hline
 265 {\em a2s\-\_\-p} & A pointer to the pair type matrix \\
 266 \hline
 267 {\em Ss\-\_\-p} & A pointer to the 'Ss' array \\
 268 \hline
 269 {\em qb\-\_\-p} & A pointer to the Q$^{\mbox{B}}$  matrix \\
 270 \hline
 271 {\em qm\-\_\-p} & A pointer to the Q$^{\mbox{M}}$  matrix \\
 272 \hline
 273 {\em q1k\-\_\-p} & A pointer to the 5' slice of the Q matrix ( $q1k(k) = Q(1, k)$) \\
 274 \hline
 275 {\em qln\-\_\-p} & A pointer to the 3' slice of the Q matrix ( $qln(l) = Q(l, n)$) \\
 276 \hline
 277 \end{DoxyParams}
 278 \begin{DoxyReturn}{Returns}
 279 Non Zero if everything went fine, 0 otherwise
 280 \end{DoxyReturn}
 281
 282
 283 \subsection{Variable Documentation}
 284 \hypertarget{group__consensus__fold_gaf3cbac6ff5d706d6e414677841ddf94c}{\index{Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}!cv\-\_\-fact@{cv\-\_\-fact}}
 285 \index{cv\-\_\-fact@{cv\-\_\-fact}!Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}}
 286 \subsubsection[{cv\-\_\-fact}]{\setlength{\rightskip}{0pt plus 5cm}double cv\-\_\-fact}}\label{group__consensus__fold_gaf3cbac6ff5d706d6e414677841ddf94c}
 287
 288
 289 This variable controls the weight of the covariance term in the energy function of alignment folding algorithms.
 290
 291 Default is 1. \hypertarget{group__consensus__fold_ga502948a122a2af5b914355b1f3ea2f61}{\index{Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}!nc\-\_\-fact@{nc\-\_\-fact}}
 292 \index{nc\-\_\-fact@{nc\-\_\-fact}!Predicting Consensus Structures from Alignment(s)@{Predicting Consensus Structures from Alignment(s)}}
 293 \subsubsection[{nc\-\_\-fact}]{\setlength{\rightskip}{0pt plus 5cm}double nc\-\_\-fact}}\label{group__consensus__fold_ga502948a122a2af5b914355b1f3ea2f61}
 294
 295
 296 This variable controls the magnitude of the penalty for non-\/compatible sequences in the covariance term of alignment folding algorithms.
 297
 298 Default is 1.