1 #ifndef VIENNA_RNA_PACKAGE_PK_PLEX_H 2 #define VIENNA_RNA_PACKAGE_PK_PLEX_H 3 4 /** 5 * @file pk_plex.h 6 * @ingroup pseudoknots 7 * @brief Heuristics for two-step pseudoknot forming interaction predictions 8 */ 9 10 /** 11 * @addtogroup pseudoknots 12 * @{ 13 * 14 * @brief Implementations to predict pseudoknotted structures 15 * 16 */ 17 18 /** 19 * @brief Pseudoknot loop scoring function prototype 20 * 21 * This function is used to evaluate a formed pseudoknot (PK) interaction in vrna_pk_plex(). 22 * It is supposed to take a PK-free secondary structure as input and coordinates 23 * of an additional interaction site. From this data, the energy (penalty) to score the 24 * PK loop is derived and returned in decakal/mol. 25 * Upon passing zero in any of the interaction site coordinates (@p start_5, @p end_5, 26 * @p start_3, @p end_3) or a @em NULL pointer in @p pt, the function must return a 27 * PK loop score. This minimum PK loop score is used in the first phase of the heuristic 28 * implemented in vrna_pk_plex() to assess whether a particular interaction is further 29 * taken into account in a later, more thorough evaluation step. 30 * 31 * The simplest scoring function would simply return a constant score for any 32 * PK loop, no matter what type of loop is formed and how large the loop is. This 33 * is the default if vrna_pk_plex_opt_defaults() or vrna_pk_plex_opt() is used to 34 * generate options for vrna_pk_plex(). 35 * 36 * @see vrna_pk_plex_opt_fun(), vrna_pk_plex() 37 * @param pt The secondary structure (without pseudoknot) in pair table notation 38 * @param start_5 The start coordinate of the 5' site of the pseudoknot interaction 39 * @param end_5 The end coordinate of the 5' site of the pseudoknot interaction 40 * @param start_3 The start coordinate of the 3' site of the pseudoknot interaction 41 * @param end_3 The end coordinate of the 3' site of the pseudoknot interaction 42 * @param data An arbitrary data structure passed from the calling function 43 * @return The energy (penalty) of the resulting pseudoknot 44 */ 45 typedef int (vrna_callback_pk_plex_score)(const short *pt, 46 int start_5, 47 int end_5, 48 int start_3, 49 int end_3, 50 void *data); 51 52 /** 53 * @brief RNA PKplex options object 54 * 55 * @see vrna_pk_plex_opt_defaults(), vrna_pk_plex_opt(), vrna_pk_plex_opt_fun(), 56 * vrna_pk_plex(), #vrna_callback_pk_plex_score 57 */ 58 typedef struct vrna_pk_plex_option_s *vrna_pk_plex_opt_t; 59 60 /** 61 * @brief Convenience typedef for results of the RNA PKplex prediction 62 * 63 * @see #vrna_pk_plex_results_s, vrna_pk_plex() 64 */ 65 typedef struct vrna_pk_plex_result_s vrna_pk_plex_t; 66 67 #include <ViennaRNA/fold_compound.h> 68 69 /** 70 * @brief A result of the RNA PKplex interaction prediction 71 * 72 * @see #vrna_pk_plex_t 73 */ 74 struct vrna_pk_plex_result_s { 75 char *structure; /**< @brief Secondary Structure in dot-bracket notation */ 76 double energy; /**< @brief Net free energy in kcal/mol */ 77 double dGpk; /**< @brief Free energy of PK loop in kcal/mol */ 78 double dGint; /**< @brief Free energy of PK forming duplex interaction */ 79 double dG1; /**< @brief Opening energy for the 5' interaction site used in the heuristic */ 80 double dG2; /**< @brief Opening energy for the 3' interaction site used in the heuristic */ 81 unsigned int start_5; /**< @brief Start coordinate of the 5' interaction site */ 82 unsigned int end_5; /**< @brief End coordinate of the 5' interaction site */ 83 unsigned int start_3; /**< @brief Start coordinate of the 3' interaction site */ 84 unsigned int end_3; /**< @brief End coordinate of the 3' interaction site */ 85 }; 86 87 /** 88 * @brief Predict Pseudoknot interactions in terms of a two-step folding process 89 * 90 * Computes simple pseudoknot interactions according to the PKplex algorithm. This 91 * simple heuristic first compiles a list of potential interaction sites that may 92 * form a pseudoknot. The resulting candidate interactions are then fixed and an 93 * PK-free MFE structure for the remainder of the sequence is computed. 94 * 95 * The @p accessibility argument is a list of opening energies for potential 96 * interaction sites. It is used in the first step of the algorithm to identify 97 * potential interactions. Upon passing @em NULL, the opening energies are determined 98 * automatically based on the current model settings. 99 * 100 * Depending on the @p options, the function can return the MFE (incl. PK loops) 101 * or suboptimal structures within an energy band around the MFE. The PK loop is 102 * internally scored by a scoring function that in the simplest cases assigns a 103 * constant value for each PK loop. More complicated scoring functions can be 104 * passed as well, see #vrna_callback_pk_plex_score and vrna_pk_plex_opt_fun(). 105 * 106 * The function returns @em NULL on any error. Otherwise, a list of structures 107 * and interaction coordinates with corresponding energy contributions is returned. 108 * If no PK-interaction that satisfies the options is found, the list only 109 * consists of the PK-free MFE structure. 110 * 111 * @param fc fold compound with the input sequence and model settings 112 * @param accessibility An array of opening energies for the implemented heuristic (maybe @em NULL) 113 * @param options An #vrna_pk_plex_opt_t options data structure that determines the algorithm parameters 114 * @return A list of potentially pseudoknotted structures (Last element in the list indicated by @em NULL value in #vrna_pk_plex_result_s.structure) 115 */ 116 vrna_pk_plex_t * 117 vrna_pk_plex(vrna_fold_compound_t *fc, 118 const int **accessibility, 119 vrna_pk_plex_opt_t options); 120 121 122 /** 123 * @brief Obtain a list of opening energies suitable for PKplex computations 124 * 125 * @see vrna_pk_plex() 126 * 127 * @param sequence The RNA sequence 128 * @param unpaired The maximum number of unpaired nucleotides, i.e. length of interaction 129 * @param cutoff A cutoff value for unpaired probabilities 130 * @return Opening energies as required for vrna_pk_plex() 131 */ 132 int ** 133 vrna_pk_plex_accessibility(const char *sequence, 134 unsigned int unpaired, 135 double cutoff); 136 137 138 /** 139 * @brief Default options for PKplex algorithm 140 * 141 * @see vrna_pk_plex(), vrna_pk_plex_opt(), vrna_pk_plex_opt_fun() 142 * 143 * @return An options data structure suitabe for PKplex computations 144 */ 145 vrna_pk_plex_opt_t 146 vrna_pk_plex_opt_defaults(void); 147 148 149 /** 150 * @brief Simple options for PKplex algorithm 151 * 152 * @see vrna_pk_plex(), vrna_pk_plex_opt_defaults(), vrna_pk_plex_opt_fun() 153 * 154 * @param delta Size of energy band around MFE for suboptimal results in dekacal/mol 155 * @param max_interaction_length Maximum length of interaction 156 * @param pk_penalty Energy constant to score the PK forming loop 157 * @return An options data structure suitabe for PKplex computations 158 */ 159 vrna_pk_plex_opt_t 160 vrna_pk_plex_opt(unsigned int delta, 161 unsigned int max_interaction_length, 162 int pk_penalty); 163 164 165 /** 166 * @brief Simple options for PKplex algorithm 167 * 168 * @see vrna_pk_plex(), vrna_pk_plex_opt_defaults(), vrna_pk_plex_opt(), #vrna_callback_pk_plex_score 169 * 170 * @param delta Size of energy band around MFE for suboptimal results in dekacal/mol 171 * @param max_interaction_length Maximum length of interaction 172 * @param scoring_function Energy evaluating function to score the PK forming loop 173 * @param scoring_data An arbitrary data structure passed to the scoring function (maybe @em NUL) 174 * @return An options data structure suitabe for PKplex computations 175 */ 176 vrna_pk_plex_opt_t 177 vrna_pk_plex_opt_fun(unsigned int delta, 178 unsigned int max_interaction_length, 179 vrna_callback_pk_plex_score *scoring_function, 180 void *scoring_data); 181 182 183 /** 184 * @} 185 */ 186 187 #endif 188