1 #ifndef VIENNA_RNA_PACKAGE_MFE_WINDOW_H 2 #define VIENNA_RNA_PACKAGE_MFE_WINDOW_H 3 4 #include <stdio.h> 5 #include <ViennaRNA/fold_compound.h> 6 7 #ifdef VRNA_WITH_SVM 8 #include <ViennaRNA/zscore.h> 9 #endif 10 11 /** 12 * 13 * @file mfe_window.h 14 * @ingroup mfe, mfe_window 15 * @brief Compute local Minimum Free Energy (MFE) using a sliding window approach and 16 * backtrace corresponding secondary structures 17 * 18 * This file includes the interface to all functions related to predicting locally 19 * stable secondary structures. 20 */ 21 22 23 /** 24 * @addtogroup mfe_window 25 * @{ 26 * @brief Variations of the local (sliding window) Minimum Free Energy (MFE) prediction algorithm 27 * 28 * We provide implementations for the local (sliding window) MFE prediction algorithm for 29 * * Single sequences, 30 * * Multiple sequence alignments (MSA), and 31 * 32 * Note, that our implementation scans an RNA sequence (or MSA) from the 3' to the 5' 33 * end, and reports back locally optimal (consensus) structures, the corresponding free 34 * energy, and the position of the sliding window in global coordinates. 35 * 36 * For any particular RNA sequence (or MSA) multiple locally optimal (consensus) 37 * secondary structures may be predicted. Thus, we tried to implement an interface that 38 * allows for an effortless conversion of the corresponding hits into any target data 39 * structure. As a consequence, we provide two distinct ways to retrieve the corresponding 40 * predictions, either 41 * * through directly writing to an open @p FILE stream on-the-fly, or 42 * * through a callback function mechanism. 43 * 44 * The latter allows one to store the results in any possible target data structure. Our 45 * implementations then pass the results through the user-implemented callback as soon as 46 * the prediction for a particular window is finished. 47 */ 48 49 /** 50 * @brief The default callback for sliding window MFE structure predictions 51 * 52 * @callback 53 * @parblock 54 * This function will be called for each hit in a sliding window MFE prediction. 55 * @endparblock 56 * @see vrna_mfe_window() 57 * 58 * @param start provides the first position of the hit (1-based, relative to entire sequence/alignment) 59 * @param end provides the last position of the hit (1-based, relative to the entire sequence/alignment) 60 * @param structure provides the (sub)structure in dot-bracket notation 61 * @param en is the free energy of the structure hit in kcal/mol 62 * @param data is some arbitrary data pointer passed through by the function executing the callback 63 */ 64 typedef void (vrna_mfe_window_callback)(int start, 65 int end, 66 const char *structure, 67 float en, 68 void *data); 69 70 71 #ifdef VRNA_WITH_SVM 72 typedef void (vrna_mfe_window_zscore_callback)(int start, 73 int end, 74 const char *structure, 75 float en, 76 float zscore, 77 void *data); 78 #endif 79 80 /** 81 * @name Basic local (sliding window) MFE prediction interface 82 * @{ 83 */ 84 85 /** 86 * @brief Local MFE prediction using a sliding window approach. 87 * 88 * Computes minimum free energy structures using a sliding window 89 * approach, where base pairs may not span outside the window. 90 * In contrast to vrna_mfe(), where a maximum base pair span 91 * may be set using the #vrna_md_t.max_bp_span attribute and one 92 * globally optimal structure is predicted, this function uses a 93 * sliding window to retrieve all locally optimal structures within 94 * each window. 95 * The size of the sliding window is set in the #vrna_md_t.window_size 96 * attribute, prior to the retrieval of the #vrna_fold_compound_t 97 * using vrna_fold_compound() with option #VRNA_OPTION_WINDOW 98 * 99 * The predicted structures are written on-the-fly, either to 100 * stdout, if a NULL pointer is passed as file parameter, or to 101 * the corresponding filehandle. 102 * 103 * @see vrna_fold_compound(), vrna_mfe_window_zscore(), vrna_mfe(), 104 * vrna_Lfold(), vrna_Lfoldz(), 105 * #VRNA_OPTION_WINDOW, #vrna_md_t.max_bp_span, #vrna_md_t.window_size 106 * 107 * @param vc The #vrna_fold_compound_t with preallocated memory for the DP matrices 108 * @param file The output file handle where predictions are written to (maybe NULL) 109 */ 110 float 111 vrna_mfe_window(vrna_fold_compound_t *vc, 112 FILE *file); 113 114 115 float 116 vrna_mfe_window_cb(vrna_fold_compound_t *vc, 117 vrna_mfe_window_callback *cb, 118 void *data); 119 120 121 #ifdef VRNA_WITH_SVM 122 /** 123 * @brief Local MFE prediction using a sliding window approach (with z-score cut-off) 124 * 125 * Computes minimum free energy structures using a sliding window 126 * approach, where base pairs may not span outside the window. 127 * This function is the z-score version of vrna_mfe_window(), i.e. 128 * only predictions above a certain z-score cut-off value are 129 * printed. 130 * As for vrna_mfe_window(), the size of the sliding window is set in 131 * the #vrna_md_t.window_size attribute, prior to the retrieval of 132 * the #vrna_fold_compound_t using vrna_fold_compound() with option 133 * #VRNA_OPTION_WINDOW. 134 * 135 * The predicted structures are written on-the-fly, either to 136 * stdout, if a NULL pointer is passed as file parameter, or to 137 * the corresponding filehandle. 138 * 139 * @see vrna_fold_compound(), vrna_mfe_window_zscore(), vrna_mfe(), 140 * vrna_Lfold(), vrna_Lfoldz(), 141 * #VRNA_OPTION_WINDOW, #vrna_md_t.max_bp_span, #vrna_md_t.window_size 142 * 143 * @param vc The #vrna_fold_compound_t with preallocated memory for the DP matrices 144 * @param min_z The minimal z-score for a predicted structure to appear in the output 145 * @param file The output file handle where predictions are written to (maybe NULL) 146 */ 147 float 148 vrna_mfe_window_zscore(vrna_fold_compound_t *vc, 149 double min_z, 150 FILE *file); 151 152 153 float 154 vrna_mfe_window_zscore_cb(vrna_fold_compound_t *vc, 155 double min_z, 156 vrna_mfe_window_zscore_callback *cb, 157 void *data); 158 159 160 #endif 161 162 /* End basic local MFE interface */ 163 /**@}*/ 164 165 /** 166 * @name Simplified local MFE prediction using sequence(s) or multiple sequence alignment(s) 167 * @{ 168 */ 169 170 /** 171 * @brief Local MFE prediction using a sliding window approach (simplified interface) 172 * 173 * This simplified interface to vrna_mfe_window() computes the MFE and locally 174 * optimal secondary structure using default options. Structures are predicted 175 * using a sliding window approach, where base pairs may not span outside the 176 * window. Memory required for dynamic programming (DP) matrices will 177 * be allocated and free'd on-the-fly. Hence, after return of this function, the recursively filled 178 * matrices are not available any more for any post-processing. 179 * 180 * @note In case you want to use the filled DP matrices for any subsequent post-processing step, or 181 * you require other conditions than specified by the default model details, use vrna_mfe_window(), 182 * and the data structure #vrna_fold_compound_t instead. 183 * 184 * @see vrna_mfe_window(), vrna_Lfoldz(), vrna_mfe_window_zscore() 185 * 186 * @param string The nucleic acid sequence 187 * @param window_size The window size for locally optimal structures 188 * @param file The output file handle where predictions are written to (if NULL, output is written to stdout) 189 */ 190 float 191 vrna_Lfold(const char *string, 192 int window_size, 193 FILE *file); 194 195 196 float 197 vrna_Lfold_cb(const char *string, 198 int window_size, 199 vrna_mfe_window_callback *cb, 200 void *data); 201 202 203 #ifdef VRNA_WITH_SVM 204 /** 205 * @brief Local MFE prediction using a sliding window approach with z-score cut-off (simplified interface) 206 * 207 * This simplified interface to vrna_mfe_window_zscore() computes the MFE and locally 208 * optimal secondary structure using default options. Structures are predicted 209 * using a sliding window approach, where base pairs may not span outside the 210 * window. Memory required for dynamic programming (DP) matrices will 211 * be allocated and free'd on-the-fly. Hence, after return of this function, the recursively filled 212 * matrices are not available any more for any post-processing. 213 * This function is the z-score version of vrna_Lfold(), i.e. 214 * only predictions above a certain z-score cut-off value are 215 * printed. 216 * 217 * @note In case you want to use the filled DP matrices for any subsequent post-processing step, or 218 * you require other conditions than specified by the default model details, use vrna_mfe_window(), 219 * and the data structure #vrna_fold_compound_t instead. 220 * 221 * @see vrna_mfe_window_zscore(), vrna_Lfold(), vrna_mfe_window() 222 * 223 * @param string The nucleic acid sequence 224 * @param window_size The window size for locally optimal structures 225 * @param min_z The minimal z-score for a predicted structure to appear in the output 226 * @param file The output file handle where predictions are written to (if NULL, output is written to stdout) 227 */ 228 float 229 vrna_Lfoldz(const char *string, 230 int window_size, 231 double min_z, 232 FILE *file); 233 234 235 float 236 vrna_Lfoldz_cb(const char *string, 237 int window_size, 238 double min_z, 239 vrna_mfe_window_zscore_callback *cb, 240 void *data); 241 242 243 #endif 244 245 float vrna_aliLfold(const char **alignment, 246 int maxdist, 247 FILE *fp); 248 249 250 float vrna_aliLfold_cb(const char **alignment, 251 int maxdist, 252 vrna_mfe_window_callback *cb, 253 void *data); 254 255 256 /* End simplified local MFE interface */ 257 /**@}*/ 258 259 /* End group mfe_fold_window */ 260 /**@}*/ 261 262 263 #endif 264