binaries/src/ViennaRNA/H/fold.h

   1 #ifndef __VIENNA_RNA_PACKAGE_FOLD_H__
   2 #define __VIENNA_RNA_PACKAGE_FOLD_H__
   3
   4 #include "data_structures.h"
   5
   6 #ifdef __GNUC__
   7 #define DEPRECATED(func) func __attribute__ ((deprecated))
   8 #else
   9 #define DEPRECATED(func) func
  10 #endif
  11
  12 /**
  13  *  \addtogroup mfe_fold
  14  *  \ingroup folding_routines
  15  *  \brief This section covers all functions and variables related to the calculation
  16  *  of minimum free energy (MFE) structures.
  17  *
  18  *  The library provides a fast dynamic programming minimum free energy
  19  *  folding algorithm as described in \cite zuker:1981.
  20  *  All relevant parts that directly implement the "Zuker & Stiegler" algorithm for single
  21  *  sequences are described in this section.
  22  *
  23  *  Folding of circular RNA sequences is handled as a post-processing step of the forward
  24  *  recursions. See \cite hofacker:2006 for further details.
  25  *
  26  *  Nevertheless, the RNAlib also
  27  *  provides interfaces for the prediction of consensus MFE structures of sequence alignments,
  28  *  MFE structure for two hybridized sequences, local optimal structures and many more. For
  29  *  those more specialized variants of MFE folding routines, please consult the appropriate
  30  *  subsections (Modules) as listed above.
  31  *
  32  *  \file fold.h
  33  *  \brief MFE calculations and energy evaluations for single RNA sequences
  34  *
  35  *  This file includes (almost) all function declarations within the RNAlib that are related to
  36  *  MFE folding...
  37  */
  38
  39 /**
  40  *  \defgroup eval Energy evaluation
  41  *  @{
  42  *    \brief This module contains all functions and variables related to energy evaluation
  43  *    of sequence/structure pairs.
  44  *
  45  *
  46  *  @}
  47  */
  48
  49 /**
  50  *  \defgroup mfe_fold Calculating Minimum Free Energy Structures
  51  *  @{
  52  *    \brief This module contains all functions and variables related to the calculation
  53  *    of global minimum free energy structures for single sequences.
  54  *
  55  *    The library provides a fast dynamic programming minimum free energy
  56  *    folding algorithm as described by \ref zuker_81 "Zuker & Stiegler (1981)".
  57  *  @}
  58  */
  59
  60 /** \brief if nonzero use logarithmic ML energy in energy_of_struct  */
  61 extern  int logML;
  62
  63 /** \brief do ML decomposition uniquely (for subopt)  */
  64 extern  int uniq_ML;
  65
  66 /** \brief set to first pos of second seq for cofolding  */
  67 extern  int cut_point;
  68
  69 /**
  70  *  \brief verbose info from energy_of_struct
  71  *  \ingroup eval
  72  */
  73 extern  int eos_debug;
  74
  75
  76 /**
  77  *  \brief Compute minimum free energy and an appropriate secondary
  78  *  structure of an RNA sequence
  79  *
  80  *  The first parameter given, the RNA sequence, must be \a uppercase and should only contain
  81  *  an alphabet \f$\Sigma\f$ that is understood by the RNAlib\n
  82  *  (e.g. \f$ \Sigma = \{A,U,C,G\} \f$)\n
  83  *
  84  *  The second parameter, \a structure, must always point to an allocated
  85  *  block of memory with a size of at least \f$\mathrm{strlen}(\mathrm{sequence})+1\f$
  86  *
  87  *  If the third parameter is NULL, global model detail settings are assumed for the folding
  88  *  recursions. Otherwise, the provided parameters are used.
  89  *
  90  *  The fourth parameter indicates whether a secondary structure constraint in enhanced dot-bracket
  91  *  notation is passed through the structure parameter or not. If so, the characters " | x < > " are
  92  *  recognized to mark bases that are paired, unpaired, paired upstream, or downstream, respectively.
  93  *  Matching brackets " ( ) " denote base pairs, dots "." are used for unconstrained bases.
  94  *
  95  *  To indicate that the RNA sequence is circular and thus has to be post-processed, set the last
  96  *  parameter to non-zero
  97  *
  98  *  After a successful call of fold_par(), a backtracked secondary structure (in dot-bracket notation)
  99  *  that exhibits the minimum of free energy will be written to the memory \a structure is pointing to.
 100  *  The function returns the minimum of free energy for any fold of the sequence given.
 101  *
 102  *  \note OpenMP: Passing NULL to the 'parameters' argument involves access to several global model
 103  *        detail variables and thus is not to be considered threadsafe
 104  *
 105  *  \ingroup mfe_fold
 106  *
 107  *  \see fold(), circfold(), #model_detailsT, set_energy_model(), get_scaled_parameters()
 108  *
 109  *  \param sequence       RNA sequence
 110  *  \param structure      A pointer to the character array where the
 111  *                        secondary structure in dot-bracket notation will be written to
 112  *  \param parameters     A data structure containing the prescaled energy contributions
 113  *                        and the model details. (NULL may be passed, see OpenMP notes above)
 114  *  \param is_constrained Switch to indicate that a structure contraint is passed via the structure argument (0==off)
 115  *  \param is_circular    Switch to (de-)activate postprocessing steps in case RNA sequence is circular (0==off)
 116  *
 117  *  \return the minimum free energy (MFE) in kcal/mol
 118  */
 119 float fold_par( const char *sequence,
 120                 char *structure,
 121                 paramT *parameters,
 122                 int is_constrained,
 123                 int is_circular);
 124
 125 /**
 126  *  \brief Compute minimum free energy and an appropriate secondary structure of an RNA sequence
 127  *
 128  *  This function essentially does the same thing as fold_par(). However, it takes its model details,
 129  *  i.e. #temperature, #dangles, #tetra_loop, #noGU, #no_closingGU, #fold_constrained, #noLonelyPairs
 130  *  from the current global settings within the library
 131  *
 132  *  Use fold_par() for a completely threadsafe variant
 133  *
 134  *  \ingroup mfe_fold
 135  *
 136  *  \see fold_par(), circfold()
 137  *
 138  *  \param sequence RNA sequence
 139  *  \param structure A pointer to the character array where the
 140  *         secondary structure in dot-bracket notation will be written to
 141  *  \return the minimum free energy (MFE) in kcal/mol
 142  */
 143 float fold( const char *sequence,
 144             char *structure);
 145
 146 /**
 147  *  \brief Compute minimum free energy and an appropriate secondary structure of a circular RNA sequence
 148  *
 149  *  This function essentially does the same thing as fold_par(). However, it takes its model details,
 150  *  i.e. #temperature, #dangles, #tetra_loop, #noGU, #no_closingGU, #fold_constrained, #noLonelyPairs
 151  *  from the current global settings within the library
 152  *
 153  *  Use fold_par() for a completely threadsafe variant
 154  *
 155  *  \ingroup mfe_fold
 156  *
 157  *  \see fold_par(), circfold()
 158  *
 159  *  \param sequence RNA sequence
 160  *  \param structure A pointer to the character array where the
 161  *         secondary structure in dot-bracket notation will be written to
 162  *  \return the minimum free energy (MFE) in kcal/mol
 163  */
 164 float circfold( const char *sequence,
 165                 char *structure);
 166
 167
 168 /**
 169  *  \addtogroup eval Energy evaluation
 170  *  \ingroup folding_routines
 171  *  @{
 172  *    \brief This module contains all functions and variables related to energy evaluation
 173  *    of sequence/structure pairs.
 174  *  @}
 175  */
 176
 177 /**
 178  *  \brief Calculate the free energy of an already folded RNA using global model detail settings
 179  *
 180  *  If verbosity level is set to a value >0, energies of structure elements are printed to stdout
 181  *
 182  *  \note OpenMP: This function relies on several global model settings variables and thus is
 183  *        not to be considered threadsafe. See energy_of_struct_par() for a completely threadsafe
 184  *        implementation.
 185  *
 186  *  \ingroup eval
 187  *
 188  *  \see energy_of_struct_par(), energy_of_circ_structure()
 189  *
 190  *  \param string     RNA sequence
 191  *  \param structure  secondary structure in dot-bracket notation
 192  *  \param verbosity_level a flag to turn verbose output on/off
 193  *  \return          the free energy of the input structure given the input sequence in kcal/mol
 194  */
 195 float energy_of_structure(const char *string,
 196                           const char *structure,
 197                           int verbosity_level);
 198
 199 /**
 200  *  \brief Calculate the free energy of an already folded RNA
 201  *
 202  *  If verbosity level is set to a value >0, energies of structure elements are printed to stdout
 203  *
 204  *  \ingroup eval
 205  *
 206  *  \see energy_of_circ_structure(), energy_of_structure_pt(), get_scaled_parameters()
 207  *
 208  *  \param string           RNA sequence in uppercase letters
 209  *  \param structure        Secondary structure in dot-bracket notation
 210  *  \param parameters       A data structure containing the prescaled energy contributions and the model details.
 211  *  \param verbosity_level  A flag to turn verbose output on/off
 212  *  \return                The free energy of the input structure given the input sequence in kcal/mol
 213  */
 214 float energy_of_struct_par( const char *string,
 215                             const char *structure,
 216                             paramT *parameters,
 217                             int verbosity_level);
 218
 219 /**
 220  *  \brief Calculate the free energy of an already folded  circular RNA
 221  *
 222  *  \note OpenMP: This function relies on several global model settings variables and thus is
 223  *        not to be considered threadsafe. See energy_of_circ_struct_par() for a completely threadsafe
 224  *        implementation.
 225  *
 226  *  If verbosity level is set to a value >0, energies of structure elements are printed to stdout
 227  *
 228  *  \ingroup eval
 229  *
 230  *  \see energy_of_circ_struct_par(), energy_of_struct_par()
 231  *
 232  *  \param string           RNA sequence
 233  *  \param structure        Secondary structure in dot-bracket notation
 234  *  \param verbosity_level  A flag to turn verbose output on/off
 235  *  \return                The free energy of the input structure given the input sequence in kcal/mol
 236  */
 237 float energy_of_circ_structure( const char *string,
 238                                 const char *structure,
 239                                 int verbosity_level);
 240
 241 /**
 242  *  \brief Calculate the free energy of an already folded circular RNA
 243  *
 244  *  If verbosity level is set to a value >0, energies of structure elements are printed to stdout
 245  *
 246  *  \ingroup eval
 247  *
 248  *  \see energy_of_struct_par(), get_scaled_parameters()
 249  *
 250  *  \param string           RNA sequence
 251  *  \param structure        Secondary structure in dot-bracket notation
 252  *  \param parameters       A data structure containing the prescaled energy contributions and the model details.
 253  *  \param verbosity_level  A flag to turn verbose output on/off
 254  *  \return                The free energy of the input structure given the input sequence in kcal/mol
 255  */
 256 float energy_of_circ_struct_par(const char *string,
 257                                 const char *structure,
 258                                 paramT *parameters,
 259                                 int verbosity_level);
 260
 261
 262 float energy_of_gquad_structure(const char *string,
 263                                 const char *structure,
 264                                 int verbosity_level);
 265
 266 /**
 267  *  \brief Calculate the free energy of an already folded RNA
 268  *
 269  *  If verbosity level is set to a value >0, energies of structure elements are printed to stdout
 270  *
 271  *  \note OpenMP: This function relies on several global model settings variables and thus is
 272  *        not to be considered threadsafe. See energy_of_struct_pt_par() for a completely threadsafe
 273  *        implementation.
 274  *
 275  *  \ingroup eval
 276  *
 277  *  \see make_pair_table(), energy_of_struct_pt_par()
 278  *
 279  *  \param string     RNA sequence
 280  *  \param ptable     the pair table of the secondary structure
 281  *  \param s          encoded RNA sequence
 282  *  \param s1         encoded RNA sequence
 283  *  \param verbosity_level a flag to turn verbose output on/off
 284  *  \return          the free energy of the input structure given the input sequence in 10kcal/mol
 285  */
 286 int energy_of_structure_pt( const char *string,
 287                             short *ptable,
 288                             short *s,
 289                             short *s1,
 290                             int verbosity_level);
 291
 292 /**
 293  *  \brief Calculate the free energy of an already folded RNA
 294  *
 295  *  If verbosity level is set to a value >0, energies of structure elements are printed to stdout
 296  *
 297  *  \ingroup eval
 298  *
 299  *  \see make_pair_table(), energy_of_struct_par(), get_scaled_parameters()
 300  *
 301  *  \param string           RNA sequence in uppercase letters
 302  *  \param ptable           The pair table of the secondary structure
 303  *  \param s                Encoded RNA sequence
 304  *  \param s1               Encoded RNA sequence
 305  *  \param parameters       A data structure containing the prescaled energy contributions and the model details.
 306  *  \param verbosity_level  A flag to turn verbose output on/off
 307  *  \return                The free energy of the input structure given the input sequence in 10kcal/mol
 308  */
 309 int energy_of_struct_pt_par(const char *string,
 310                             short *ptable,
 311                             short *s,
 312                             short *s1,
 313                             paramT *parameters,
 314                             int verbosity_level);
 315
 316 /**
 317  *  \brief Free arrays for mfe folding
 318  *
 319  *  \ingroup mfe_fold
 320  *
 321  */
 322 void  free_arrays(void);
 323
 324
 325 /**
 326  *  \brief Create a dot-backet/parenthesis structure from backtracking stack
 327  *
 328  *  \note This function is threadsafe
 329  */
 330 void  parenthesis_structure(char *structure,
 331                             bondT *bp,
 332                             int length);
 333
 334 /**
 335  *  \brief Create a dot-backet/parenthesis structure from backtracking stack
 336  *  obtained by zuker suboptimal calculation in cofold.c
 337  *
 338  *  \note This function is threadsafe
 339  */
 340 void parenthesis_zuker( char *structure,
 341                         bondT *bp,
 342                         int length);
 343
 344 void letter_structure(char *structure,
 345                       bondT *bp,
 346                       int length);
 347
 348
 349 /**
 350  *  \brief Recalculate energy parameters
 351  *
 352  *  \ingroup mfe_fold
 353  */
 354 void  update_fold_params(void);
 355
 356 /**
 357  *
 358  *  \ingroup mfe_fold
 359  *
 360  */
 361 void update_fold_params_par(paramT *parameters);
 362
 363 /**
 364  *
 365  *  \ingroup mfe_fold
 366  *
 367  */
 368 char  *backtrack_fold_from_pair(char *sequence,
 369                                 int i,
 370                                 int j);
 371
 372 /**
 373  * \brief Calculate energy of a move (closing or opening of a base pair)
 374  *
 375  *  If the parameters m1 and m2 are negative, it is deletion (opening)
 376  *  of a base pair, otherwise it is insertion (opening).
 377  *
 378  *  \see              make_pair_table(), energy_of_move()
 379  *  \param string     RNA sequence
 380  *  \param structure  secondary structure in dot-bracket notation
 381  *  \param m1         first coordinate of base pair
 382  *  \param m2         second coordinate of base pair
 383  *  \returns          energy change of the move in kcal/mol
 384  */
 385 float energy_of_move( const char *string,
 386                       const char *structure,
 387                       int m1,
 388                       int m2);
 389
 390
 391 /**
 392  *
 393  * \brief Calculate energy of a move (closing or opening of a base pair)
 394  *
 395  *  If the parameters m1 and m2 are negative, it is deletion (opening)
 396  *  of a base pair, otherwise it is insertion (opening).
 397  *
 398  *  \see              make_pair_table(), energy_of_move()
 399  *  \param pt         the pair table of the secondary structure
 400  *  \param s          encoded RNA sequence
 401  *  \param s1         encoded RNA sequence
 402  *  \param m1         first coordinate of base pair
 403  *  \param m2         second coordinate of base pair
 404  *  \returns          energy change of the move in 10cal/mol
 405  */
 406 int energy_of_move_pt(short *pt,
 407                    short *s,
 408                    short *s1,
 409                    int m1,
 410                    int m2);
 411
 412 /**
 413  * \brief Calculate energy of a loop
 414  *
 415  *  \param ptable     the pair table of the secondary structure
 416  *  \param s          encoded RNA sequence
 417  *  \param s1         encoded RNA sequence
 418  *  \param i          position of covering base pair
 419  *  \returns          free energy of the loop in 10cal/mol
 420  */
 421 int   loop_energy(short *ptable,
 422                   short *s,
 423                   short *s1,
 424                   int i);
 425
 426 /**
 427  *
 428  *  \ingroup mfe_fold
 429  *
 430  */
 431 void export_fold_arrays(int **f5_p,
 432                         int **c_p,
 433                         int **fML_p,
 434                         int **fM1_p,
 435                         int **indx_p,
 436                         char **ptype_p);
 437
 438 /**
 439  *
 440  *  \ingroup mfe_fold
 441  *
 442  */
 443 void export_fold_arrays_par(int **f5_p,
 444                             int **c_p,
 445                             int **fML_p,
 446                             int **fM1_p,
 447                             int **indx_p,
 448                             char **ptype_p,
 449                             paramT **P_p);
 450
 451 /**
 452  *
 453  *  \ingroup mfe_fold
 454  *
 455  */
 456 void export_circfold_arrays(int *Fc_p,
 457                             int *FcH_p,
 458                             int *FcI_p,
 459                             int *FcM_p,
 460                             int **fM2_p,
 461                             int **f5_p,
 462                             int **c_p,
 463                             int **fML_p,
 464                             int **fM1_p,
 465                             int **indx_p,
 466                             char **ptype_p);
 467
 468 /**
 469  *
 470  *  \ingroup mfe_fold
 471  *
 472  */
 473 void export_circfold_arrays_par(int *Fc_p,
 474                                 int *FcH_p,
 475                                 int *FcI_p,
 476                                 int *FcM_p,
 477                                 int **fM2_p,
 478                                 int **f5_p,
 479                                 int **c_p,
 480                                 int **fML_p,
 481                                 int **fM1_p,
 482                                 int **indx_p,
 483                                 char **ptype_p,
 484                                 paramT **P_p);
 485
 486
 487 /**
 488  *  \brief Create a plist from a dot-bracket string
 489  *
 490  *  The dot-bracket string is parsed and for each base pair an
 491  *  entry in the plist is created. The probability of each pair in
 492  *  the list is set by a function parameter.
 493  *
 494  *  The end of the plist is marked by sequence positions i as well as j
 495  *  equal to 0. This condition should be used to stop looping over its
 496  *  entries
 497  *
 498  *  This function is threadsafe
 499  *
 500  *  \param pl     A pointer to the plist that is to be created
 501  *  \param struc  The secondary structure in dot-bracket notation
 502  *  \param pr     The probability for each base pair
 503  */
 504 void assign_plist_from_db(plist **pl,
 505                           const char *struc,
 506                           float pr);
 507
 508 /* finally moved the loop energy function declarations to this header...  */
 509 /* BUT: The functions only exist for backward compatibility reasons!      */
 510 /* You better include "loop_energies.h" and call the functions:           */
 511 /* E_Hairpin() and E_IntLoop() which are (almost) threadsafe as they get  */
 512 /* a pointer to the energy parameter datastructure as additional argument */
 513
 514 /**
 515  *  \deprecated {This function is deprecated and will be removed soon.
 516  *  Use \ref E_IntLoop() instead!}
 517  */
 518 DEPRECATED(int LoopEnergy(int n1,
 519                           int n2,
 520                           int type,
 521                           int type_2,
 522                           int si1,
 523                           int sj1,
 524                           int sp1,
 525                           int sq1));
 526
 527 /**
 528  *  \deprecated {This function is deprecated and will be removed soon.
 529  *  Use \ref E_Hairpin() instead!}
 530  */
 531 DEPRECATED(int HairpinE(int size,
 532                         int type,
 533                         int si1,
 534                         int sj1,
 535                         const char *string));
 536
 537 /**
 538  *  Allocate arrays for folding\n
 539  *  \deprecated {This function is deprecated and will be removed soon!}
 540  *
 541  */
 542 DEPRECATED(void initialize_fold(int length));
 543
 544 /**
 545  *  Calculate the free energy of an already folded RNA
 546  *
 547  *  \note This function is not entirely threadsafe! Depending on the state of the global
 548  *  variable \ref eos_debug it prints energy information to stdout or not...\n
 549  *
 550  *  \deprecated This function is deprecated and should not be used in future programs!
 551  *  Use \ref energy_of_structure() instead!
 552  *
 553  *  \see              energy_of_structure, energy_of_circ_struct(), energy_of_struct_pt()
 554  *  \param string     RNA sequence
 555  *  \param structure  secondary structure in dot-bracket notation
 556  *  \return          the free energy of the input structure given the input sequence in kcal/mol
 557  */
 558 DEPRECATED(float energy_of_struct(const char *string,
 559                                   const char *structure));
 560
 561 /**
 562  *  Calculate the free energy of an already folded RNA
 563  *
 564  *  \note This function is not entirely threadsafe! Depending on the state of the global
 565  *  variable \ref eos_debug it prints energy information to stdout or not...\n
 566  *
 567  *  \deprecated This function is deprecated and should not be used in future programs!
 568  *  Use \ref energy_of_structure_pt() instead!
 569  *
 570  *  \see              make_pair_table(), energy_of_structure()
 571  *  \param string     RNA sequence
 572  *  \param ptable     the pair table of the secondary structure
 573  *  \param s          encoded RNA sequence
 574  *  \param s1         encoded RNA sequence
 575  *  \return          the free energy of the input structure given the input sequence in 10kcal/mol
 576  */
 577 DEPRECATED(int energy_of_struct_pt( const char *string,
 578                                     short *ptable,
 579                                     short *s,
 580                                     short *s1));
 581
 582 /**
 583  *  Calculate the free energy of an already folded  circular RNA
 584  *
 585  *  \note This function is not entirely threadsafe! Depending on the state of the global
 586  *  variable \ref eos_debug it prints energy information to stdout or not...\n
 587  *
 588  *  \deprecated This function is deprecated and should not be used in future programs
 589  *  Use \ref energy_of_circ_structure() instead!
 590  *
 591  *  \see              energy_of_circ_structure(), energy_of_struct(), energy_of_struct_pt()
 592  *  \param string     RNA sequence
 593  *  \param structure  secondary structure in dot-bracket notation
 594  *  \return          the free energy of the input structure given the input sequence in kcal/mol
 595  */
 596 DEPRECATED(float energy_of_circ_struct( const char *string,
 597                                         const char *structure));
 598
 599 #endif