1 #ifndef VIENNA_RNA_PACKAGE_CONSTRAINTS_H 2 #define VIENNA_RNA_PACKAGE_CONSTRAINTS_H 3 4 #include <ViennaRNA/fold_compound.h> 5 6 /** 7 * @file constraints/basic.h 8 * @ingroup constraints 9 * @brief Functions and data structures for constraining secondary structure predictions and evaluation 10 */ 11 12 /** 13 * @addtogroup constraints 14 * 15 * @brief This module provides general functions that allow for an easy control of 16 * constrained secondary structure prediction and evaluation. 17 * 18 * Secondary Structure constraints can be subdivided into two groups: 19 * 20 * - @ref hard_constraints, and 21 * - @ref soft_constraints. 22 * 23 * While Hard-Constraints directly influence the production rules used in the folding 24 * recursions by allowing, disallowing, or enforcing certain decomposition steps, 25 * Soft-constraints on the other hand are used to change position specific contributions 26 * in the recursions by adding bonuses/penalties in form of pseudo free energies 27 * to certain loop configurations. 28 * 29 * Secondary structure constraints are always applied at decomposition level, i.e. 30 * in each step of the recursive structure decomposition, for instance during MFE 31 * prediction. Below is a visualization of the decomposition scheme 32 * 33 * @image html recursions.svg 34 * @image latex recursions.eps 35 * 36 * For @ref hard_constraints the following option flags may be used to constrain 37 * the pairing behavior of single, or pairs of nucleotides: 38 * 39 * - #VRNA_CONSTRAINT_CONTEXT_EXT_LOOP - @copybrief #VRNA_CONSTRAINT_CONTEXT_EXT_LOOP 40 * - #VRNA_CONSTRAINT_CONTEXT_HP_LOOP - @copybrief #VRNA_CONSTRAINT_CONTEXT_HP_LOOP 41 * - #VRNA_CONSTRAINT_CONTEXT_INT_LOOP - @copybrief #VRNA_CONSTRAINT_CONTEXT_INT_LOOP 42 * - #VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC - @copybrief #VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC 43 * - #VRNA_CONSTRAINT_CONTEXT_MB_LOOP - @copybrief #VRNA_CONSTRAINT_CONTEXT_MB_LOOP 44 * - #VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC - @copybrief #VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC 45 * - #VRNA_CONSTRAINT_CONTEXT_ENFORCE - @copybrief #VRNA_CONSTRAINT_CONTEXT_ENFORCE 46 * - #VRNA_CONSTRAINT_CONTEXT_NO_REMOVE - @copybrief #VRNA_CONSTRAINT_CONTEXT_NO_REMOVE 47 * - #VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS - @copybrief #VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS 48 * 49 * However, for @ref soft_constraints we do not allow for simple loop type 50 * dependent constraining. But soft constraints are equipped with generic constraint 51 * support. This enables the user to pass arbitrary callback functions that 52 * return auxiliary energy contributions for evaluation the evaluation of any 53 * decomposition. 54 * 55 * The callback will then always be notified about the type of decomposition 56 * that is happening, and the corresponding delimiting sequence positions. The 57 * following decomposition steps are distinguished, and should be captured by 58 * the user's implementation of the callback: 59 * 60 * - #VRNA_DECOMP_PAIR_HP - @copybrief #VRNA_DECOMP_PAIR_HP 61 * - #VRNA_DECOMP_PAIR_IL - @copybrief #VRNA_DECOMP_PAIR_IL 62 * - #VRNA_DECOMP_PAIR_ML - @copybrief #VRNA_DECOMP_PAIR_ML 63 * - #VRNA_DECOMP_ML_ML_ML - @copybrief #VRNA_DECOMP_ML_ML_ML 64 * - #VRNA_DECOMP_ML_STEM - @copybrief #VRNA_DECOMP_ML_STEM 65 * - #VRNA_DECOMP_ML_ML - @copybrief #VRNA_DECOMP_ML_ML 66 * - #VRNA_DECOMP_ML_UP - @copybrief #VRNA_DECOMP_ML_UP 67 * - #VRNA_DECOMP_ML_ML_STEM - @copybrief #VRNA_DECOMP_ML_ML_STEM 68 * - #VRNA_DECOMP_ML_COAXIAL - @copybrief #VRNA_DECOMP_ML_COAXIAL 69 * - #VRNA_DECOMP_EXT_EXT - @copybrief #VRNA_DECOMP_EXT_EXT 70 * - #VRNA_DECOMP_EXT_UP - @copybrief #VRNA_DECOMP_EXT_UP 71 * - #VRNA_DECOMP_EXT_STEM - @copybrief #VRNA_DECOMP_EXT_STEM 72 * - #VRNA_DECOMP_EXT_EXT_EXT - @copybrief #VRNA_DECOMP_EXT_EXT_EXT 73 * - #VRNA_DECOMP_EXT_STEM_EXT - @copybrief #VRNA_DECOMP_EXT_STEM_EXT 74 * - #VRNA_DECOMP_EXT_STEM_OUTSIDE - @copybrief #VRNA_DECOMP_EXT_STEM_OUTSIDE 75 * - #VRNA_DECOMP_EXT_EXT_STEM - @copybrief #VRNA_DECOMP_EXT_EXT_STEM 76 * - #VRNA_DECOMP_EXT_EXT_STEM1 - @copybrief #VRNA_DECOMP_EXT_EXT_STEM1 77 * 78 * Simplified interfaces to the soft constraints framework can be obtained 79 * by the implementations in the submodules 80 * 81 * - @ref SHAPE_reactivities and 82 * - @ref constraints_ligand. 83 * 84 * An implementation that generates soft constraints for unpaired nucleotides 85 * by minimizing the discrepancy between their predicted and expected pairing 86 * probability is available in submodule @ref perturbation. 87 * 88 */ 89 90 91 /** 92 * @brief Flag for vrna_constraints_add() to indicate that constraints are present in a text file 93 * 94 * @see vrna_constraints_add() 95 * @deprecated Use 0 instead! 96 * @ingroup constraints 97 * 98 */ 99 #define VRNA_CONSTRAINT_FILE 0 100 101 /** 102 * @brief Indicate generation of constraints for MFE folding 103 * @deprecated This flag has no meaning anymore, since constraints are now always stored! 104 * @ingroup constraints 105 * 106 */ 107 #define VRNA_CONSTRAINT_SOFT_MFE 0 108 109 /** 110 * @brief Indicate generation of constraints for partition function computation 111 * @deprecated Use #VRNA_OPTION_PF instead! 112 * @ingroup constraints 113 * 114 */ 115 #define VRNA_CONSTRAINT_SOFT_PF VRNA_OPTION_PF 116 117 /** 118 * @brief Flag passed to generic softt constraints callback to indicate hairpin loop decomposition step 119 * 120 * @ingroup constraints 121 * 122 * @details This flag notifies the soft or hard constraint callback function that the current 123 * decomposition step evaluates a hairpin loop enclosed by the base pair @f$(i,j)@f$. 124 * 125 * @image html decomp_hp.svg 126 * @image latex decomp_hp.eps 127 * 128 */ 129 #define VRNA_DECOMP_PAIR_HP (unsigned char)1 130 131 /** 132 * @brief Indicator for interior loop decomposition step 133 * 134 * @ingroup constraints 135 * 136 * @details This flag notifies the soft or hard constraint callback function that the current 137 * decomposition step evaluates an interior loop enclosed by the base pair @f$(i,j)@f$, 138 * and enclosing the base pair @f$(k,l)@f$. 139 * 140 * @image html decomp_il.svg 141 * @image latex decomp_il.eps 142 * 143 */ 144 #define VRNA_DECOMP_PAIR_IL (unsigned char)2 145 146 /** 147 * @brief Indicator for multibranch loop decomposition step 148 * 149 * @ingroup constraints 150 * 151 * @details This flag notifies the soft or hard constraint callback function that the current 152 * decomposition step evaluates a multibranch loop enclosed by the base pair @f$(i,j)@f$, 153 * and consisting of some enclosed multi loop content from k to l. 154 * 155 * @image html decomp_ml.svg 156 * @image latex decomp_ml.eps 157 * 158 */ 159 #define VRNA_DECOMP_PAIR_ML (unsigned char)3 160 #define VRNA_DECOMP_PAIR_ML_EXT (unsigned char)23 161 162 #define VRNA_DECOMP_PAIR_ML_OUTSIDE (unsigned char)4 163 /** 164 * @brief Indicator for decomposition of multibranch loop part 165 * 166 * @ingroup constraints 167 * 168 * @details This flag notifies the soft or hard constraint callback function that the current 169 * decomposition step evaluates a multibranch loop part in the interval @f$[i:j]@f$, 170 * which will be decomposed into two multibranch loop parts @f$[i:k]@f$, and @f$[l:j]@f$. 171 * 172 * @image html decomp_ml_ml_ml.svg 173 * @image latex decomp_ml_ml_ml.eps 174 * 175 */ 176 #define VRNA_DECOMP_ML_ML_ML (unsigned char)5 177 178 /** 179 * @brief Indicator for decomposition of multibranch loop part 180 * 181 * @ingroup constraints 182 * 183 * @details This flag notifies the soft or hard constraint callback function that the current 184 * decomposition step evaluates a multibranch loop part in the interval @f$[i:j]@f$, 185 * which will be considered a single stem branching off with base pair @f$(k,l)@f$. 186 * 187 * @image html decomp_ml_stem.svg 188 * @image latex decomp_ml_stem.eps 189 * 190 */ 191 #define VRNA_DECOMP_ML_STEM (unsigned char)6 192 193 /** 194 * @brief Indicator for decomposition of multibranch loop part 195 * 196 * @ingroup constraints 197 * 198 * @details This flag notifies the soft or hard constraint callback function that the current 199 * decomposition step evaluates a multibranch loop part in the interval @f$[i:j]@f$, 200 * which will be decomposed into a (usually) smaller multibranch loop part @f$[k:l]@f$. 201 * 202 * @image html decomp_ml_ml.svg 203 * @image latex decomp_ml_ml.eps 204 * 205 */ 206 #define VRNA_DECOMP_ML_ML (unsigned char)7 207 208 /** 209 * @brief Indicator for decomposition of multibranch loop part 210 * 211 * @ingroup constraints 212 * 213 * @details This flag notifies the soft or hard constraint callback function that the current 214 * decomposition step evaluates a multibranch loop part in the interval @f$[i:j]@f$, 215 * which will be considered a multibranch loop part that only consists of unpaired 216 * nucleotides. 217 * 218 * @image html decomp_ml_up.svg 219 * @image latex decomp_ml_up.eps 220 * 221 */ 222 #define VRNA_DECOMP_ML_UP (unsigned char)8 223 224 /** 225 * @brief Indicator for decomposition of multibranch loop part 226 * 227 * @ingroup constraints 228 * 229 * @details This flag notifies the soft or hard constraint callback function that the current 230 * decomposition step evaluates a multibranch loop part in the interval @f$[i:j]@f$, 231 * which will decomposed into a multibranch loop part @f$[i:k]@f$, and a stem with 232 * enclosing base pair @f$(l,j)@f$. 233 * 234 * @image html decomp_ml_ml_stem.svg 235 * @image latex decomp_ml_ml_stem.eps 236 * 237 */ 238 #define VRNA_DECOMP_ML_ML_STEM (unsigned char)9 239 240 /** 241 * @brief Indicator for decomposition of multibranch loop part 242 * 243 * @ingroup constraints 244 * 245 * @details This flag notifies the soft or hard constraint callback function that the current 246 * decomposition step evaluates a multibranch loop part in the interval @f$[i:j]@f$, 247 * where two stems with enclosing pairs @f$(i,k)@f$ and @f$(l,j)@f$ are coaxially stacking 248 * onto each other. 249 * 250 * @image html decomp_ml_coaxial.svg 251 * @image latex decomp_ml_coaxial.eps 252 * 253 */ 254 #define VRNA_DECOMP_ML_COAXIAL (unsigned char)10 255 256 /** 257 * @brief Indicator for decomposition of multibranch loop part 258 * 259 * @ingroup constraints 260 * 261 * @details This flag notifies the soft or hard constraint callback function that the current 262 * decomposition step evaluates a multibranch loop part in the interval @f$[i:j]@f$, 263 * where two stems with enclosing pairs @f$(i,k)@f$ and @f$(l,j)@f$ are coaxially stacking 264 * onto each other. 265 * 266 * @image html decomp_ml_coaxial.svg 267 * @image latex decomp_ml_coaxial.eps 268 * 269 */ 270 #define VRNA_DECOMP_ML_COAXIAL_ENC (unsigned char)11 271 272 /** 273 * @brief Indicator for decomposition of exterior loop part 274 * 275 * @ingroup constraints 276 * 277 * @def VRNA_DECOMP_EXT_EXT 278 * @details This flag notifies the soft or hard constraint callback function that the current 279 * decomposition step evaluates an exterior loop part in the interval @f$[i:j]@f$, 280 * which will be decomposed into a (usually) smaller exterior loop part @f$[k:l]@f$. 281 * 282 * @image html decomp_ext_ext.svg 283 * @image latex decomp_ext_ext.eps 284 * 285 */ 286 #define VRNA_DECOMP_EXT_EXT (unsigned char)12 287 288 /** 289 * @brief Indicator for decomposition of exterior loop part 290 * 291 * @ingroup constraints 292 * 293 * @details This flag notifies the soft or hard constraint callback function that the current 294 * decomposition step evaluates an exterior loop part in the interval @f$[i:j]@f$, 295 * which will be considered as an exterior loop component consisting of only unpaired 296 * nucleotides. 297 * 298 * @image html decomp_ext_up.svg 299 * @image latex decomp_ext_up.eps 300 * 301 */ 302 #define VRNA_DECOMP_EXT_UP (unsigned char)13 303 304 /** 305 * @brief Indicator for decomposition of exterior loop part 306 * 307 * @ingroup constraints 308 * 309 * @details This flag notifies the soft or hard constraint callback function that the current 310 * decomposition step evaluates an exterior loop part in the interval @f$[i:j]@f$, 311 * which will be considered a stem with enclosing pair @f$(k,l)@f$. 312 * 313 * @image html decomp_ext_stem.svg 314 * @image latex decomp_ext_stem.eps 315 * 316 */ 317 #define VRNA_DECOMP_EXT_STEM (unsigned char)14 318 319 /** 320 * @brief Indicator for decomposition of exterior loop part 321 * 322 * @ingroup constraints 323 * 324 * @details This flag notifies the soft or hard constraint callback function that the current 325 * decomposition step evaluates an exterior loop part in the interval @f$[i:j]@f$, 326 * which will be decomposed into two exterior loop parts @f$[i:k]@f$ and @f$[l:j]@f$. 327 * 328 * @image html decomp_ext_ext_ext.svg 329 * @image latex decomp_ext_ext_ext.eps 330 * 331 */ 332 #define VRNA_DECOMP_EXT_EXT_EXT (unsigned char)15 333 334 /** 335 * @brief Indicator for decomposition of exterior loop part 336 * 337 * @ingroup constraints 338 * 339 * @details This flag notifies the soft or hard constraint callback function that the current 340 * decomposition step evaluates an exterior loop part in the interval @f$[i:j]@f$, 341 * which will be decomposed into a stem branching off with base pair @f$(i,k)@f$, and 342 * an exterior loop part @f$[l:j]@f$. 343 * 344 * @image html decomp_ext_stem_ext.svg 345 * @image latex decomp_ext_stem_ext.eps 346 * 347 */ 348 #define VRNA_DECOMP_EXT_STEM_EXT (unsigned char)16 349 350 /** 351 * @brief Indicator for decomposition of exterior loop part 352 * 353 * @ingroup constraints 354 * 355 */ 356 #define VRNA_DECOMP_EXT_STEM_OUTSIDE (unsigned char)17 357 358 /** 359 * @brief Indicator for decomposition of exterior loop part 360 * 361 * @ingroup constraints 362 * 363 * @details This flag notifies the soft or hard constraint callback function that the current 364 * decomposition step evaluates an exterior loop part in the interval @f$[i:j]@f$, 365 * which will be decomposed into an exterior loop part @f$[i:k]@f$, and a stem 366 * branching off with base pair @f$(l,j)@f$. 367 * 368 * @image html decomp_ext_ext_stem.svg 369 * @image latex decomp_ext_ext_stem.eps 370 * 371 */ 372 #define VRNA_DECOMP_EXT_EXT_STEM (unsigned char)18 373 374 /** 375 * @brief Indicator for decomposition of exterior loop part 376 * 377 * @ingroup constraints 378 * 379 * @def VRNA_DECOMP_EXT_EXT_STEM1 380 * @details This flag notifies the soft or hard constraint callback function that the current 381 * decomposition step evaluates an exterior loop part in the interval @f$[i:j]@f$, 382 * which will be decomposed into an exterior loop part @f$[i:k]@f$, and a stem 383 * branching off with base pair @f$(l,j-1)@f$. 384 * 385 * @image html decomp_ext_ext_stem1.svg 386 * @image latex decomp_ext_ext_stem1.eps 387 * 388 */ 389 #define VRNA_DECOMP_EXT_EXT_STEM1 (unsigned char)19 390 391 #define VRNA_DECOMP_EXT_STEM_EXT1 (unsigned char)20 392 393 #define VRNA_DECOMP_EXT_L (unsigned char)21 394 #define VRNA_DECOMP_EXT_EXT_L (unsigned char)22 395 396 /** 397 * @brief Add constraints to a #vrna_fold_compound_t data structure 398 * 399 * Use this function to add/update the hard/soft constraints 400 * The function allows for passing a string 'constraint' that can either be a 401 * filename that points to a constraints definition file or it may be a 402 * pseudo dot-bracket notation indicating hard constraints. For the latter, the 403 * user has to pass the #VRNA_CONSTRAINT_DB option. Also, the 404 * user has to specify, which characters are allowed to be interpreted as 405 * constraints by passing the corresponding options via the third parameter. 406 * 407 * @see vrna_hc_init(), vrna_hc_add_up(), vrna_hc_add_up_batch(), vrna_hc_add_bp(), 408 * vrna_sc_init(), vrna_sc_set_up(), vrna_sc_set_bp(), 409 * vrna_sc_add_SHAPE_deigan(), vrna_sc_add_SHAPE_zarringhalam(), 410 * vrna_hc_free(), vrna_sc_free(), 411 * #VRNA_CONSTRAINT_DB, #VRNA_CONSTRAINT_DB_DEFAULT, #VRNA_CONSTRAINT_DB_PIPE, 412 * #VRNA_CONSTRAINT_DB_DOT, #VRNA_CONSTRAINT_DB_X, #VRNA_CONSTRAINT_DB_ANG_BRACK, 413 * #VRNA_CONSTRAINT_DB_RND_BRACK, #VRNA_CONSTRAINT_DB_INTRAMOL, 414 * #VRNA_CONSTRAINT_DB_INTERMOL, #VRNA_CONSTRAINT_DB_GQUAD 415 * 416 * @ingroup constraints 417 * 418 * The following is an example for adding hard constraints given in 419 * pseudo dot-bracket notation. Here, @p vc is the #vrna_fold_compound_t object, 420 * @p structure is a char array with the hard constraint in dot-bracket notation, 421 * and @p enforceConstraints is a flag indicating whether or not constraints for 422 * base pairs should be enforced instead of just doing a removal of base pair that 423 * conflict with the constraint. 424 * 425 * @snippet RNAfold.c Adding hard constraints from pseudo dot-bracket 426 * 427 * In constrat to the above, constraints may also be read from file: 428 * 429 * @snippet RNAfold.c Adding hard constraints from file 430 * 431 * @see vrna_hc_add_from_db(), vrna_hc_add_up(), vrna_hc_add_up_batch() 432 * vrna_hc_add_bp_unspecific(), vrna_hc_add_bp() 433 * 434 * @param vc The fold compound 435 * @param constraint A string with either the filename of the constraint definitions 436 * or a pseudo dot-bracket notation of the hard constraint. May be NULL. 437 * @param options The option flags 438 */ 439 void vrna_constraints_add(vrna_fold_compound_t *vc, 440 const char *constraint, 441 unsigned int options); 442 443 444 #endif 445