1 #ifndef VIENNA_RNA_PACKAGE_PART_FUNC_WINDOW_H 2 #define VIENNA_RNA_PACKAGE_PART_FUNC_WINDOW_H 3 4 /** 5 * @file part_func_window.h 6 * @ingroup pf_fold, part_func_window 7 * @brief Partition function and equilibrium probability implementation for the sliding window algorithm 8 * 9 * This file contains the implementation for sliding window partition function and equilibrium 10 * probabilities. It also provides the unpaired probability implementation from Bernhart et al. 11 * 2011 @cite bernhart:2011 12 */ 13 14 15 #include <ViennaRNA/datastructures/basic.h> 16 17 /** 18 * @addtogroup part_func_window 19 * @{ 20 * @brief Scanning version using a sliding window approach to compute equilibrium 21 * probabilities 22 */ 23 24 /** 25 * @brief Sliding window probability computation callback 26 * 27 * @callback 28 * @parblock 29 * This function will be called for each probability data set in the sliding 30 * window probability computation implementation of vrna_probs_window(). 31 * The argument @a type specifies the type of probability that is passed to 32 * this function. 33 * @endparblock 34 * 35 * #### Types: #### 36 * * #VRNA_PROBS_WINDOW_BPP - @copybrief #VRNA_PROBS_WINDOW_BPP 37 * * #VRNA_PROBS_WINDOW_UP - @copybrief #VRNA_PROBS_WINDOW_UP 38 * * #VRNA_PROBS_WINDOW_PF - @copybrief #VRNA_PROBS_WINDOW_PF 39 * 40 * The above types usually come exclusively. However, for unpaired 41 * probabilities, the #VRNA_PROBS_WINDOW_UP flag is OR-ed together 42 * with one of the loop type contexts 43 * 44 * * #VRNA_EXT_LOOP - @copybrief #VRNA_EXT_LOOP 45 * * #VRNA_HP_LOOP - @copybrief #VRNA_HP_LOOP 46 * * #VRNA_INT_LOOP - @copybrief #VRNA_INT_LOOP 47 * * #VRNA_MB_LOOP - @copybrief #VRNA_MB_LOOP 48 * * #VRNA_ANY_LOOP - @copybrief #VRNA_ANY_LOOP 49 * 50 * to indicate the particular type of data available through the @p pr 51 * pointer. 52 * 53 * @see vrna_probs_window(), vrna_pfl_fold_up_cb() 54 * 55 * @param pr An array of probabilities 56 * @param pr_size The length of the probability array 57 * @param i The i-position (5') of the probabilities 58 * @param max The (theoretical) maximum length of the probability array 59 * @param type The type of data that is provided 60 * @param data Auxiliary data 61 */ 62 63 typedef void (vrna_probs_window_callback)(FLT_OR_DBL *pr, 64 int pr_size, 65 int i, 66 int max, 67 unsigned int type, 68 void *data); 69 70 #include <ViennaRNA/fold_compound.h> 71 #include <ViennaRNA/utils/structures.h> 72 73 /** 74 * @brief Exterior loop 75 */ 76 #define VRNA_EXT_LOOP 1U 77 78 /** 79 * @brief Hairpin loop 80 */ 81 #define VRNA_HP_LOOP 2U 82 83 /** 84 * @brief Internal loop 85 */ 86 #define VRNA_INT_LOOP 4U 87 88 /** 89 * @brief Multibranch loop 90 */ 91 #define VRNA_MB_LOOP 8U 92 93 /** 94 * @brief Any loop 95 */ 96 #define VRNA_ANY_LOOP (VRNA_EXT_LOOP | VRNA_HP_LOOP | VRNA_INT_LOOP | VRNA_MB_LOOP) 97 98 99 /** 100 * @brief Trigger base pairing probabilities 101 * 102 * Passing this flag to vrna_probs_window() activates callback execution for base 103 * pairing probabilities. In turn, the corresponding callback receives this flag 104 * through the @p type argument whenever base pairing probabilities are provided. 105 * 106 * Detailed information for the algorithm to compute unpaired probabilities 107 * can be taken from @cite bernhart:2005. 108 * 109 * @see vrna_probs_window() 110 */ 111 #define VRNA_PROBS_WINDOW_BPP 4096U 112 113 /** 114 * @brief Trigger unpaired probabilities 115 * 116 * Passing this flag to vrna_probs_window() activates callback execution for 117 * unpaired probabilities. In turn, the corresponding callback receives this flag 118 * through the @p type argument whenever unpaired probabilities are provided. 119 * 120 * Detailed information for the algorithm to compute unpaired probabilities 121 * can be taken from @cite bernhart:2011. 122 * 123 * @see vrna_probs_window() 124 */ 125 #define VRNA_PROBS_WINDOW_UP 8192U 126 127 /** 128 * @brief Trigger base pair stack probabilities 129 * 130 * Passing this flag to vrna_probs_window() activates callback execution for 131 * stacking probabilities. In turn, the corresponding callback receives this flag 132 * through the @p type argument whenever stack probabilities are provided. 133 * 134 * @bug Currently, this flag is a placeholder doing nothing as the corresponding 135 * implementation for stack probability computation is missing. 136 * 137 * @see vrna_probs_window() 138 */ 139 #define VRNA_PROBS_WINDOW_STACKP 16384U 140 141 /** 142 * @brief Trigger detailed unpaired probabilities split up into different loop type contexts 143 * 144 * Passing this flag to vrna_probs_window() activates callback execution for 145 * unpaired probabilities. In contrast to #VRNA_PROBS_WINDOW_UP this flag requests 146 * unpaired probabilities to be split up into different loop type contexts. In turn, 147 * the corresponding callback receives the #VRNA_PROBS_WINDOW_UP flag OR-ed together 148 * with the corresponding loop type, i.e.: 149 * 150 * * #VRNA_EXT_LOOP - @copybrief #VRNA_EXT_LOOP 151 * * #VRNA_HP_LOOP - @copybrief #VRNA_HP_LOOP 152 * * #VRNA_INT_LOOP - @copybrief #VRNA_INT_LOOP 153 * * #VRNA_MB_LOOP - @copybrief #VRNA_MB_LOOP 154 * * #VRNA_ANY_LOOP - @copybrief #VRNA_ANY_LOOP 155 * 156 * @see vrna_probs_window(), #VRNA_PROBS_WINDOW_UP 157 */ 158 #define VRNA_PROBS_WINDOW_UP_SPLIT 32768U 159 160 161 /** 162 * @brief Trigger partition function 163 * 164 * Passing this flag to vrna_probs_window() activates callback execution for 165 * partition function. In turn, the corresponding callback receives this flag 166 * through it's @p type argument whenever partition function data is provided. 167 * 168 * @note Instead of actually providing the partition function @f$Z@f$, the 169 * callback is always provided with the corresponding enemble free energy 170 * @f$\Delta G = - RT \ln Z@f$. 171 * 172 * @see vrna_probs_window() 173 */ 174 #define VRNA_PROBS_WINDOW_PF 65536U 175 176 /** 177 * @name Basic local partition function interface 178 * @{ 179 */ 180 181 /** 182 * @brief Compute various equilibrium probabilities under a sliding window approach 183 * 184 * This function applies a sliding window scan for the sequence provided with the 185 * argument @p fc and reports back equilibrium probabilities through the callback 186 * function @p cb. The data reported to the callback depends on the @p options flag. 187 * 188 * @note The parameter @p ulength only affects computation and resulting data if unpaired 189 * probability computations are requested through the @p options flag. 190 * 191 * #### Options: #### 192 * * #VRNA_PROBS_WINDOW_BPP - @copybrief #VRNA_PROBS_WINDOW_BPP 193 * * #VRNA_PROBS_WINDOW_UP - @copybrief #VRNA_PROBS_WINDOW_UP 194 * * #VRNA_PROBS_WINDOW_UP_SPLIT - @copybrief #VRNA_PROBS_WINDOW_UP_SPLIT 195 * 196 * Options may be OR-ed together 197 * 198 * @see vrna_pfl_fold_cb(), vrna_pfl_fold_up_cb() 199 * 200 * @param fc The fold compound with sequence data, model settings and precomputed energy parameters 201 * @param ulength The maximal length of an unpaired segment (only for unpaired probability computations) 202 * @param cb The callback function which collects the pair probability data for further processing 203 * @param data Some arbitrary data structure that is passed to the callback @p cb 204 * @param options Option flags to control the behavior of this function 205 * @return 0 on failure, non-zero on success 206 */ 207 int 208 vrna_probs_window(vrna_fold_compound_t *fc, 209 int ulength, 210 unsigned int options, 211 vrna_probs_window_callback *cb, 212 void *data); 213 214 /* End basic interface */ 215 /**@}*/ 216 217 /** 218 * @name Simplified global partition function computation using sequence(s) or multiple sequence alignment(s) 219 * @{ 220 */ 221 222 /** 223 * @brief Compute base pair probabilities using a sliding-window approach 224 * 225 * This is a simplified wrapper to vrna_probs_window() that given a nucleid acid sequence, 226 * a window size, a maximum base pair span, and a cutoff value computes the pair probabilities 227 * for any base pair in any window. The pair probabilities are returned as a list and the user 228 * has to take care to free() the memory occupied by the list. 229 * 230 * @note This function uses default model settings! For custom model settings, we refer to 231 * the function vrna_probs_window(). 232 * 233 * @note In case of any computation errors, this function returns @p NULL 234 * 235 * @see vrna_probs_window(), vrna_pfl_fold_cb(), vrna_pfl_fold_up() 236 * 237 * @param sequence The nucleic acid input sequence 238 * @param window_size The size of the sliding window 239 * @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs 240 * @param cutoff A cutoff value that omits all pairs with lower probability 241 * @return A list of base pair probabilities, terminated by an entry with #vrna_ep_t.i and #vrna_ep_t.j set to 0 242 */ 243 vrna_ep_t * 244 vrna_pfl_fold(const char *sequence, 245 int window_size, 246 int max_bp_span, 247 float cutoff); 248 249 250 /** 251 * @brief Compute base pair probabilities using a sliding-window approach (callback version) 252 * 253 * This is a simplified wrapper to vrna_probs_window() that given a nucleid acid sequence, 254 * a window size, a maximum base pair span, and a cutoff value computes the pair probabilities 255 * for any base pair in any window. It is similar to vrna_pfl_fold() but uses a callback mechanism 256 * to return the pair probabilities. 257 * 258 * Read the details for vrna_probs_window() for details on the callback implementation! 259 * 260 * @note This function uses default model settings! For custom model settings, we refer to 261 * the function vrna_probs_window(). 262 * 263 * @see vrna_probs_window(), vrna_pfl_fold(), vrna_pfl_fold_up_cb() 264 * 265 * @param sequence The nucleic acid input sequence 266 * @param window_size The size of the sliding window 267 * @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs 268 * @param cb The callback function which collects the pair probability data for further processing 269 * @param data Some arbitrary data structure that is passed to the callback @p cb 270 * @return 0 on failure, non-zero on success 271 */ 272 int 273 vrna_pfl_fold_cb(const char *sequence, 274 int window_size, 275 int max_bp_span, 276 vrna_probs_window_callback *cb, 277 void *data); 278 279 280 /** 281 * @brief Compute probability of contiguous unpaired segments 282 * 283 * This is a simplified wrapper to vrna_probs_window() that given a nucleic acid sequence, 284 * a maximum length of unpaired segments (@p ulength), a window size, and a maximum base 285 * pair span computes the equilibrium probability of any segment not exceeding @p ulength. 286 * The probabilities to be unpaired are returned as a 1-based, 2-dimensional matrix with 287 * dimensions @f$ N \times M @f$, where @f$N@f$ is the length of the sequence and @f$M@f$ 288 * is the maximum segment length. As an example, the probability of a segment of size 5 289 * starting at position 100 is stored in the matrix entry @f$X[100][5]@f$. 290 * 291 * It is the users responsibility to free the memory occupied by this matrix. 292 * 293 * @note This function uses default model settings! For custom model settings, we refer to 294 * the function vrna_probs_window(). 295 * 296 * @param sequence The nucleic acid input sequence 297 * @param ulength The maximal length of an unpaired segment 298 * @param window_size The size of the sliding window 299 * @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs 300 * @return The probabilities to be unpaired for any segment not exceeding @p ulength 301 */ 302 double ** 303 vrna_pfl_fold_up(const char *sequence, 304 int ulength, 305 int window_size, 306 int max_bp_span); 307 308 309 /** 310 * @brief Compute probability of contiguous unpaired segments 311 * 312 * This is a simplified wrapper to vrna_probs_window() that given a nucleic acid sequence, 313 * a maximum length of unpaired segments (@p ulength), a window size, and a maximum base 314 * pair span computes the equilibrium probability of any segment not exceeding @p ulength. 315 * It is similar to vrna_pfl_fold_up() but uses a callback mechanism to return the unpaired 316 * probabilities. 317 * 318 * Read the details for vrna_probs_window() for details on the callback implementation! 319 * 320 * 321 * @note This function uses default model settings! For custom model settings, we refer to 322 * the function vrna_probs_window(). 323 * 324 * @param sequence The nucleic acid input sequence 325 * @param ulength The maximal length of an unpaired segment 326 * @param window_size The size of the sliding window 327 * @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs 328 * @param cb The callback function which collects the pair probability data for further processing 329 * @param data Some arbitrary data structure that is passed to the callback @p cb 330 * @return 0 on failure, non-zero on success 331 */ 332 int 333 vrna_pfl_fold_up_cb(const char *sequence, 334 int ulength, 335 int window_size, 336 int max_bp_span, 337 vrna_probs_window_callback *cb, 338 void *data); 339 340 341 /* End simplified interface */ 342 /**@}*/ 343 344 345 /**@}*/ 346 347 #endif 348