1 #ifndef VIENNA_RNA_PACKAGE_PARAMS_H 2 #define VIENNA_RNA_PACKAGE_PARAMS_H 3 4 #ifdef VRNA_WARN_DEPRECATED 5 # if defined(__clang__) 6 # define DEPRECATED(func, msg) func __attribute__ ((deprecated("", msg))) 7 # elif defined(__GNUC__) 8 # define DEPRECATED(func, msg) func __attribute__ ((deprecated(msg))) 9 # else 10 # define DEPRECATED(func, msg) func 11 # endif 12 #else 13 # define DEPRECATED(func, msg) func 14 #endif 15 16 /** 17 * @file params/basic.h 18 * @ingroup energy_parameters 19 * @brief Functions to deal with sets of energy parameters 20 */ 21 22 /** 23 * @addtogroup energy_parameters 24 * @{ 25 * 26 * @brief All relevant functions to retrieve and copy pre-calculated energy parameter sets as well as 27 * reading/writing the energy parameter set from/to file(s). 28 * 29 * This module covers all relevant functions for pre-calculation of the energy parameters 30 * necessary for the folding routines provided by RNAlib. Furthermore, the energy parameter set 31 * in the RNAlib can be easily exchanged by a user-defined one. It is also possible to write the 32 * current energy parameter set into a text file. 33 */ 34 35 /** @brief Typename for the free energy parameter data structure #vrna_params */ 36 typedef struct vrna_param_s vrna_param_t; 37 /** @brief Typename for the Boltzmann factor data structure #vrna_exp_params */ 38 typedef struct vrna_exp_param_s vrna_exp_param_t; 39 40 #include <ViennaRNA/params/constants.h> 41 #include <ViennaRNA/datastructures/basic.h> 42 #include <ViennaRNA/fold_compound.h> 43 #include <ViennaRNA/model.h> 44 45 #define VRNA_GQUAD_MAX_STACK_SIZE 7 46 #define VRNA_GQUAD_MIN_STACK_SIZE 2 47 #define VRNA_GQUAD_MAX_LINKER_LENGTH 15 48 #define VRNA_GQUAD_MIN_LINKER_LENGTH 1 49 #define VRNA_GQUAD_MIN_BOX_SIZE ((4 * VRNA_GQUAD_MIN_STACK_SIZE) + \ 50 (3 * VRNA_GQUAD_MIN_LINKER_LENGTH)) 51 #define VRNA_GQUAD_MAX_BOX_SIZE ((4 * VRNA_GQUAD_MAX_STACK_SIZE) + \ 52 (3 * VRNA_GQUAD_MAX_LINKER_LENGTH)) 53 54 /** 55 * @brief The datastructure that contains temperature scaled energy parameters. 56 */ 57 struct vrna_param_s { 58 int id; 59 int stack[NBPAIRS + 1][NBPAIRS + 1]; 60 int hairpin[31]; 61 int bulge[MAXLOOP + 1]; 62 int internal_loop[MAXLOOP + 1]; 63 int mismatchExt[NBPAIRS + 1][5][5]; 64 int mismatchI[NBPAIRS + 1][5][5]; 65 int mismatch1nI[NBPAIRS + 1][5][5]; 66 int mismatch23I[NBPAIRS + 1][5][5]; 67 int mismatchH[NBPAIRS + 1][5][5]; 68 int mismatchM[NBPAIRS + 1][5][5]; 69 int dangle5[NBPAIRS + 1][5]; 70 int dangle3[NBPAIRS + 1][5]; 71 int int11[NBPAIRS + 1][NBPAIRS + 1][5][5]; 72 int int21[NBPAIRS + 1][NBPAIRS + 1][5][5][5]; 73 int int22[NBPAIRS + 1][NBPAIRS + 1][5][5][5][5]; 74 int ninio[5]; 75 double lxc; 76 int MLbase; 77 int MLintern[NBPAIRS + 1]; 78 int MLclosing; 79 int TerminalAU; 80 int DuplexInit; 81 int Tetraloop_E[200]; 82 char Tetraloops[1401]; 83 int Triloop_E[40]; 84 char Triloops[241]; 85 int Hexaloop_E[40]; 86 char Hexaloops[1801]; 87 int TripleC; 88 int MultipleCA; 89 int MultipleCB; 90 int gquad[VRNA_GQUAD_MAX_STACK_SIZE + 1][3 * VRNA_GQUAD_MAX_LINKER_LENGTH + 1]; 91 int gquadLayerMismatch; 92 int gquadLayerMismatchMax; 93 94 double temperature; /**< @brief Temperature used for loop contribution scaling */ 95 96 vrna_md_t model_details; /**< @brief Model details to be used in the recursions */ 97 char param_file[256]; /**< @brief The filename the parameters were derived from, or empty string if they represent the default */ 98 }; 99 100 /** 101 * @brief The data structure that contains temperature scaled Boltzmann weights of the energy parameters. 102 */ 103 struct vrna_exp_param_s { 104 int id; /**< @brief An identifier for the data structure 105 * @deprecated This attribute will be removed in version 3 106 */ 107 double expstack[NBPAIRS + 1][NBPAIRS + 1]; 108 double exphairpin[31]; 109 double expbulge[MAXLOOP + 1]; 110 double expinternal[MAXLOOP + 1]; 111 double expmismatchExt[NBPAIRS + 1][5][5]; 112 double expmismatchI[NBPAIRS + 1][5][5]; 113 double expmismatch23I[NBPAIRS + 1][5][5]; 114 double expmismatch1nI[NBPAIRS + 1][5][5]; 115 double expmismatchH[NBPAIRS + 1][5][5]; 116 double expmismatchM[NBPAIRS + 1][5][5]; 117 double expdangle5[NBPAIRS + 1][5]; 118 double expdangle3[NBPAIRS + 1][5]; 119 double expint11[NBPAIRS + 1][NBPAIRS + 1][5][5]; 120 double expint21[NBPAIRS + 1][NBPAIRS + 1][5][5][5]; 121 double expint22[NBPAIRS + 1][NBPAIRS + 1][5][5][5][5]; 122 double expninio[5][MAXLOOP + 1]; 123 double lxc; 124 double expMLbase; 125 double expMLintern[NBPAIRS + 1]; 126 double expMLclosing; 127 double expTermAU; 128 double expDuplexInit; 129 double exptetra[40]; 130 double exptri[40]; 131 double exphex[40]; 132 char Tetraloops[1401]; 133 double expTriloop[40]; 134 char Triloops[241]; 135 char Hexaloops[1801]; 136 double expTripleC; 137 double expMultipleCA; 138 double expMultipleCB; 139 double expgquad[VRNA_GQUAD_MAX_STACK_SIZE + 1][3 * VRNA_GQUAD_MAX_LINKER_LENGTH + 1]; 140 double expgquadLayerMismatch; 141 int gquadLayerMismatchMax; 142 143 double kT; 144 double pf_scale; /**< @brief Scaling factor to avoid over-/underflows */ 145 146 double temperature; /**< @brief Temperature used for loop contribution scaling */ 147 double alpha; /**< @brief Scaling factor for the thermodynamic temperature 148 * @details This allows for temperature scaling in Boltzmann 149 * factors independently from the energy contributions. 150 * The resulting Boltzmann factors are then computed by 151 * @f$ e^{-E/(\alpha \cdot K \cdot T)} @f$ 152 */ 153 154 vrna_md_t model_details; /**< @brief Model details to be used in the recursions */ 155 char param_file[256]; /**< @brief The filename the parameters were derived from, or empty string if they represent the default */ 156 }; 157 158 159 /** 160 * @brief Get a data structure containing prescaled free energy parameters 161 * 162 * If a NULL pointer is passed for the model details parameter, the default 163 * model parameters are stored within the requested #vrna_param_t structure. 164 * 165 * @see #vrna_md_t, vrna_md_set_default(), vrna_exp_params() 166 * 167 * @param md A pointer to the model details to store inside the structure (Maybe NULL) 168 * @return A pointer to the memory location where the requested parameters are stored 169 */ 170 vrna_param_t * 171 vrna_params(vrna_md_t *md); 172 173 174 /** 175 * @brief Get a copy of the provided free energy parameters 176 * 177 * If NULL is passed as parameter, a default set of energy parameters is created 178 * and returned. 179 * 180 * @see vrna_params(), #vrna_param_t 181 * 182 * @param par The free energy parameters that are to be copied (Maybe NULL) 183 * @return A copy or a default set of the (provided) parameters 184 */ 185 vrna_param_t * 186 vrna_params_copy(vrna_param_t *par); 187 188 189 /** 190 * @brief Get a data structure containing prescaled free energy parameters 191 * already transformed to Boltzmann factors 192 * 193 * This function returns a data structure that contains all necessary precomputed 194 * energy contributions for each type of loop. 195 * 196 * In contrast to vrna_params(), the free energies within this data structure 197 * are stored as their Boltzmann factors, i.e. 198 * 199 * @f$ exp(-E / kT) @f$ 200 * 201 * where @f$ E @f$ is the free energy. 202 * 203 * If a NULL pointer is passed for the model details parameter, the default 204 * model parameters are stored within the requested #vrna_exp_param_t structure. 205 * 206 * @see #vrna_md_t, vrna_md_set_default(), vrna_params(), vrna_rescale_pf_params() 207 * 208 * @param md A pointer to the model details to store inside the structure (Maybe NULL) 209 * @return A pointer to the memory location where the requested parameters are stored 210 */ 211 vrna_exp_param_t * 212 vrna_exp_params(vrna_md_t *md); 213 214 215 /** 216 * @brief Get a data structure containing prescaled free energy parameters 217 * already transformed to Boltzmann factors (alifold version) 218 * 219 * If a NULL pointer is passed for the model details parameter, the default 220 * model parameters are stored within the requested #vrna_exp_param_t structure. 221 * 222 * @see #vrna_md_t, vrna_md_set_default(), vrna_exp_params(), vrna_params() 223 * 224 * @param n_seq The number of sequences in the alignment 225 * @param md A pointer to the model details to store inside the structure (Maybe NULL) 226 * @return A pointer to the memory location where the requested parameters are stored 227 */ 228 vrna_exp_param_t * 229 vrna_exp_params_comparative(unsigned int n_seq, 230 vrna_md_t *md); 231 232 233 /** 234 * @brief Get a copy of the provided free energy parameters (provided as Boltzmann factors) 235 * 236 * If NULL is passed as parameter, a default set of energy parameters is created 237 * and returned. 238 * 239 * @see vrna_exp_params(), #vrna_exp_param_t 240 * 241 * @param par The free energy parameters that are to be copied (Maybe NULL) 242 * @return A copy or a default set of the (provided) parameters 243 */ 244 vrna_exp_param_t * 245 vrna_exp_params_copy(vrna_exp_param_t *par); 246 247 248 /** 249 * @brief Update/Reset energy parameters data structure within a #vrna_fold_compound_t 250 * 251 * Passing NULL as second argument leads to a reset of the energy parameters within 252 * vc to their default values. Otherwise, the energy parameters provided will be copied 253 * over into vc. 254 * 255 * @see vrna_params_reset(), #vrna_param_t, #vrna_md_t, vrna_params() 256 * 257 * @param vc The #vrna_fold_compound_t that is about to receive updated energy parameters 258 * @param par The energy parameters used to substitute those within vc (Maybe NULL) 259 */ 260 void 261 vrna_params_subst(vrna_fold_compound_t *vc, 262 vrna_param_t *par); 263 264 265 /** 266 * @brief Update the energy parameters for subsequent partition function computations 267 * 268 * This function can be used to properly assign new energy parameters for partition 269 * function computations to a #vrna_fold_compound_t. For this purpose, the data of the 270 * provided pointer `params` will be copied into `vc` and a recomputation of the partition 271 * function scaling factor is issued, if the `pf_scale` attribute of `params` is less than `1.0`. 272 * 273 * Passing NULL as second argument leads to a reset of the energy parameters within 274 * vc to their default values 275 * 276 * @see vrna_exp_params_reset(), vrna_exp_params_rescale(), #vrna_exp_param_t, #vrna_md_t, 277 * vrna_exp_params() 278 * 279 * @param vc The fold compound data structure 280 * @param params A pointer to the new energy parameters 281 */ 282 void 283 vrna_exp_params_subst(vrna_fold_compound_t *vc, 284 vrna_exp_param_t *params); 285 286 287 /** 288 * @brief Rescale Boltzmann factors for partition function computations 289 * 290 * This function may be used to (automatically) rescale the Boltzmann factors used 291 * in partition function computations. Since partition functions over subsequences 292 * can easily become extremely large, the RNAlib internally rescales them to avoid 293 * numerical over- and/or underflow. Therefore, a proper scaling factor @f$s@f$ needs to 294 * be chosen that in turn is then used to normalize the corresponding 295 * partition functions @f$\hat{q}[i,j] = q[i,j] / s^{(j-i+1)}@f$. 296 * 297 * This function provides two ways to automatically adjust the scaling 298 * factor. 299 * 1. Automatic guess 300 * 2. Automatic adjustment according to MFE 301 * 302 * Passing `NULL` as second parameter activates the _automatic guess mode_. Here, 303 * the scaling factor is recomputed according to a mean free energy of `184.3*length` cal 304 * for random sequences. 305 * @note This recomputation only takes place if the `pf_scale` attribute of the 306 * `exp_params` data structure contained in `vc` has a value below `1.0`. 307 * 308 * On the other hand, if the MFE for a sequence is known, it can be used to recompute 309 * a more robust scaling factor, since it represents the lowest free energy of the entire 310 * ensemble of structures, i.e. the highest Boltzmann factor. To activate this second 311 * mode of _automatic adjustment according to MFE_, a pointer to the MFE value needs to 312 * be passed as second argument. This value is then taken to compute the scaling factor 313 * as @f$ s = exp((sfact * MFE) / kT / length )@f$, where sfact is an additional 314 * scaling weight located in the vrna_md_t data structure of `exp_params` in `vc`. 315 * 316 * The computed scaling factor @f$s@f$ will be stored as `pf_scale` attribute of the 317 * `exp_params` data structure in `vc`. 318 * 319 * @see vrna_exp_params_subst(), vrna_md_t, vrna_exp_param_t, #vrna_fold_compound_t 320 * 321 * @param vc The fold compound data structure 322 * @param mfe A pointer to the MFE (in kcal/mol) or NULL 323 */ 324 void 325 vrna_exp_params_rescale(vrna_fold_compound_t *vc, 326 double *mfe); 327 328 329 /** 330 * @brief Reset free energy parameters within a #vrna_fold_compound_t 331 * according to provided, or default model details 332 * 333 * This function allows one to rescale free energy parameters for subsequent structure 334 * prediction or evaluation according to a set of model details, e.g. temperature 335 * values. To do so, the caller provides either a pointer to a set of model details 336 * to be used for rescaling, or NULL if global default setting should be used. 337 * 338 * @see vrna_exp_params_reset(), vrna_params_subs() 339 * @param vc The fold compound data structure 340 * @param md_p A pointer to the new model details (or NULL for reset to defaults) 341 */ 342 void 343 vrna_params_reset(vrna_fold_compound_t *vc, 344 vrna_md_t *md_p); 345 346 347 /** 348 * @brief Reset Boltzmann factors for partition function computations 349 * within a #vrna_fold_compound_t according to provided, or 350 * default model details 351 * 352 * This function allows one to rescale Boltzmann factors for subsequent partition 353 * function computations according to a set of model details, e.g. temperature 354 * values. To do so, the caller provides either a pointer to a set of model details 355 * to be used for rescaling, or NULL if global default setting should be used. 356 * 357 * @see vrna_params_reset(), vrna_exp_params_subst(), vrna_exp_params_rescale() 358 * @param vc The fold compound data structure 359 * @param md_p A pointer to the new model details (or NULL for reset to defaults) 360 */ 361 void 362 vrna_exp_params_reset(vrna_fold_compound_t *vc, 363 vrna_md_t *md_p); 364 365 366 void 367 vrna_params_prepare(vrna_fold_compound_t *vc, 368 unsigned int options); 369 370 371 #ifndef VRNA_DISABLE_BACKWARD_COMPATIBILITY 372 373 /** 374 * @brief Old typename of #vrna_param_s 375 * @deprecated Use #vrna_param_t instead! 376 */ 377 typedef struct vrna_param_s paramT; 378 379 /** 380 * @brief Old typename of #vrna_exp_param_s 381 * @deprecated Use #vrna_exp_param_t instead! 382 */ 383 typedef struct vrna_exp_param_s pf_paramT; 384 385 DEPRECATED(vrna_param_t *get_parameter_copy(vrna_param_t *par), 386 "Use vrna_params_copy() instead"); 387 388 /** 389 * get a data structure of type @ref vrna_exp_param_t which contains 390 * the Boltzmann weights of several energy parameters scaled 391 * according to the current temperature 392 * 393 * @deprecated Use vrna_exp_params() instead! 394 * 395 * @return The data structure containing Boltzmann weights for use in partition function calculations 396 */ 397 DEPRECATED(vrna_exp_param_t *get_scaled_pf_parameters(void), 398 "Use vrna_params() instead"); 399 400 /** 401 * @brief Get precomputed Boltzmann factors of the loop type 402 * dependent energy contributions with independent thermodynamic 403 * temperature 404 * 405 * This function returns a data structure that contains 406 * all necessary precalculated Boltzmann factors for each 407 * loop type contribution.<br> 408 * In contrast to get_scaled_pf_parameters(), this function 409 * enables setting of independent temperatures for both, the 410 * individual energy contributions as well as the thermodynamic 411 * temperature used in 412 * @f$ exp(-\Delta G / kT) @f$ 413 * 414 * @deprecated Use vrna_exp_params() instead! 415 * 416 * @see get_scaled_pf_parameters(), get_boltzmann_factor_copy() 417 * 418 * @param temperature The temperature in degrees Celcius used for (re-)scaling the energy contributions 419 * @param betaScale A scaling value that is used as a multiplication factor for the absolute 420 * temperature of the system 421 * @param md The model details to be used 422 * @param pf_scale The scaling factor for the Boltzmann factors 423 * @return A set of precomputed Boltzmann factors 424 */ 425 DEPRECATED(vrna_exp_param_t *get_boltzmann_factors(double temperature, 426 double betaScale, 427 vrna_md_t md, 428 double pf_scale), 429 "Use vrna_exp_params() instead"); 430 431 /** 432 * @brief Get a copy of already precomputed Boltzmann factors 433 * 434 * @deprecated Use vrna_exp_params_copy() instead! 435 * 436 * @see get_boltzmann_factors(), get_scaled_pf_parameters() 437 * 438 * @param parameters The input data structure that shall be copied 439 * @return A copy of the provided Boltzmann factor data set 440 */ 441 DEPRECATED(vrna_exp_param_t *get_boltzmann_factor_copy(vrna_exp_param_t *parameters), 442 "Use vrna_exp_params_copy() instead"); 443 444 /** 445 * @brief Get precomputed Boltzmann factors of the loop type 446 * dependent energy contributions (alifold variant) 447 * 448 * @deprecated Use vrna_exp_params_comparative() instead! 449 * 450 */ 451 DEPRECATED(vrna_exp_param_t *get_scaled_alipf_parameters(unsigned int n_seq), 452 "Use vrna_exp_params_comparative() instead"); 453 454 /** 455 * @brief Get precomputed Boltzmann factors of the loop type 456 * dependent energy contributions (alifold variant) with 457 * independent thermodynamic temperature 458 * 459 * @deprecated Use vrna_exp_params_comparative() instead! 460 * 461 */ 462 DEPRECATED(vrna_exp_param_t *get_boltzmann_factors_ali(unsigned int n_seq, 463 double temperature, 464 double betaScale, 465 vrna_md_t md, 466 double pf_scale), 467 "Use vrna_exp_params_comparative() instead"); 468 469 /** 470 * @brief Get precomputed energy contributions for all the known loop types 471 * 472 * @note OpenMP: This function relies on several global model settings variables and thus is 473 * not to be considered threadsafe. See get_scaled_parameters() for a completely threadsafe 474 * implementation. 475 * 476 * @deprecated Use vrna_params() instead! 477 * 478 * @return A set of precomputed energy contributions 479 */ 480 DEPRECATED(vrna_param_t *scale_parameters(void), 481 "Use vrna_params() instead"); 482 483 /** 484 * @brief Get precomputed energy contributions for all the known loop types 485 * 486 * Call this function to retrieve precomputed energy contributions, i.e. scaled 487 * according to the temperature passed. Furthermore, this function assumes a 488 * data structure that contains the model details as well, such that subsequent 489 * folding recursions are able to retrieve the correct model settings 490 * 491 * @deprecated Use vrna_params() instead! 492 * 493 * @see #vrna_md_t, set_model_details() 494 * 495 * @param temperature The temperature in degrees Celcius 496 * @param md The model details 497 * @return precomputed energy contributions and model settings 498 */ 499 DEPRECATED(vrna_param_t *get_scaled_parameters(double temperature, 500 vrna_md_t md), 501 "Usee vrna_params() instead"); 502 503 DEPRECATED(vrna_param_t *copy_parameters(void), "Use vrna_params_copy() instead"); 504 DEPRECATED(vrna_param_t *set_parameters(vrna_param_t *dest), "Use vrna_params_copy() instead"); 505 DEPRECATED(vrna_exp_param_t *scale_pf_parameters(void), "Use vrna_exp_params() instead"); 506 DEPRECATED(vrna_exp_param_t *copy_pf_param(void), "Use vrna_exp_params_copy() instead"); 507 DEPRECATED(vrna_exp_param_t *set_pf_param(vrna_param_t *dest), 508 "Use vrna_exp_params_copy() instead"); 509 510 #endif 511 512 /** 513 * @} 514 */ 515 516 517 #endif 518