#ifndef VIENNA_RNA_PACKAGE_FOLD_H #define VIENNA_RNA_PACKAGE_FOLD_H #include #include #include #include #ifdef DEPRECATION_WARNINGS # ifdef __GNUC__ # define DEPRECATED(func) func __attribute__ ((deprecated)) # else # define DEPRECATED(func) func # endif #else # define DEPRECATED(func) func #endif /* make this interface backward compatible with RNAlib < 2.2.0 */ #define VRNA_BACKWARD_COMPAT /** * @file fold.h * @ingroup mfe_fold * @brief MFE calculations for single RNA sequences */ /** * @addtogroup mfe_fold_single * @brief This module contains all functions and variables related to the calculation * of global minimum free energy structures for single sequences. * * The library provides a fast dynamic programming minimum free energy * folding algorithm as described by "Zuker & Stiegler (1981)" @cite zuker:1981. * * @{ * @ingroup mfe_fold_single */ /** * @brief Compute Minimum Free Energy (MFE), and a corresponding secondary structure for an RNA sequence * * This simplified interface to vrna_mfe() computes the MFE and, if required, a secondary structure for an * RNA sequence using default options. Memory required for dynamic programming (DP) matrices will * be allocated and free'd on-the-fly. Hence, after return of this function, the recursively filled * matrices are not available any more for any post-processing, e.g. suboptimal backtracking, etc. * * @note In case you want to use the filled DP matrices for any subsequent post-processing step, or * you require other conditions than specified by the default model details, use vrna_mfe(), * and the data structure #vrna_fold_compound_t instead. * * @see vrna_circfold(), vrna_mfe(), vrna_fold_compound(), #vrna_fold_compound_t * * @param sequence RNA sequence * @param structure A pointer to the character array where the * secondary structure in dot-bracket notation will be written to * @return the minimum free energy (MFE) in kcal/mol */ float vrna_fold(const char *sequence, char *structure); /** * @brief Compute Minimum Free Energy (MFE), and a corresponding secondary structure for a circular RNA sequence * * This simplified interface to vrna_mfe() computes the MFE and, if required, a secondary structure for a * circular RNA sequence using default options. Memory required for dynamic programming (DP) matrices will * be allocated and free'd on-the-fly. Hence, after return of this function, the recursively filled * matrices are not available any more for any post-processing, e.g. suboptimal backtracking, etc. * * Folding of circular RNA sequences is handled as a post-processing step of the forward * recursions. See @cite hofacker:2006 for further details. * * @note In case you want to use the filled DP matrices for any subsequent post-processing step, or * you require other conditions than specified by the default model details, use vrna_mfe(), * and the data structure #vrna_fold_compound_t instead. * * @see vrna_fold(), vrna_mfe(), vrna_fold_compound(), #vrna_fold_compound_t * * @param sequence RNA sequence * @param structure A pointer to the character array where the * secondary structure in dot-bracket notation will be written to * @return the minimum free energy (MFE) in kcal/mol */ float vrna_circfold(const char *sequence, char *structure); #ifdef VRNA_BACKWARD_COMPAT /** * @brief Compute minimum free energy and an appropriate secondary * structure of an RNA sequence * * The first parameter given, the RNA sequence, must be @a uppercase and should only contain * an alphabet @f$\Sigma@f$ that is understood by the RNAlib\n * (e.g. @f$ \Sigma = \{A,U,C,G\} @f$)\n * * The second parameter, @a structure, must always point to an allocated * block of memory with a size of at least @f$\mathrm{strlen}(\mathrm{sequence})+1@f$ * * If the third parameter is NULL, global model detail settings are assumed for the folding * recursions. Otherwise, the provided parameters are used. * * The fourth parameter indicates whether a secondary structure constraint in enhanced dot-bracket * notation is passed through the structure parameter or not. If so, the characters " | x < > " are * recognized to mark bases that are paired, unpaired, paired upstream, or downstream, respectively. * Matching brackets " ( ) " denote base pairs, dots "." are used for unconstrained bases. * * To indicate that the RNA sequence is circular and thus has to be post-processed, set the last * parameter to non-zero * * After a successful call of fold_par(), a backtracked secondary structure (in dot-bracket notation) * that exhibits the minimum of free energy will be written to the memory @a structure is pointing to. * The function returns the minimum of free energy for any fold of the sequence given. * * @note OpenMP: Passing NULL to the 'parameters' argument involves access to several global model * detail variables and thus is not to be considered threadsafe * * @deprecated use vrna_mfe() instead! * * @see vrna_mfe(), fold(), circfold(), #vrna_md_t, set_energy_model(), get_scaled_parameters() * * @param sequence RNA sequence * @param structure A pointer to the character array where the * secondary structure in dot-bracket notation will be written to * @param parameters A data structure containing the pre-scaled energy contributions * and the model details. (NULL may be passed, see OpenMP notes above) * @param is_constrained Switch to indicate that a structure constraint is passed via the structure argument (0==off) * @param is_circular Switch to (de-)activate post-processing steps in case RNA sequence is circular (0==off) * * @return the minimum free energy (MFE) in kcal/mol */ DEPRECATED(float fold_par( const char *sequence, char *structure, vrna_param_t *parameters, int is_constrained, int is_circular)); /** * @brief Compute minimum free energy and an appropriate secondary structure of an RNA sequence * * This function essentially does the same thing as fold_par(). However, it takes its model details, * i.e. #temperature, #dangles, #tetra_loop, #noGU, #no_closingGU, #fold_constrained, #noLonelyPairs * from the current global settings within the library * * @deprecated use vrna_fold(), or vrna_mfe() instead! * * @see fold_par(), circfold() * * @param sequence RNA sequence * @param structure A pointer to the character array where the * secondary structure in dot-bracket notation will be written to * @return the minimum free energy (MFE) in kcal/mol */ DEPRECATED(float fold( const char *sequence, char *structure)); /** * @brief Compute minimum free energy and an appropriate secondary structure of a circular RNA sequence * * This function essentially does the same thing as fold_par(). However, it takes its model details, * i.e. #temperature, #dangles, #tetra_loop, #noGU, #no_closingGU, #fold_constrained, #noLonelyPairs * from the current global settings within the library * * @deprecated Use vrna_circfold(), or vrna_mfe() instead! * * @see fold_par(), circfold() * * @param sequence RNA sequence * @param structure A pointer to the character array where the * secondary structure in dot-bracket notation will be written to * @return the minimum free energy (MFE) in kcal/mol */ DEPRECATED(float circfold( const char *sequence, char *structure)); /** * @brief Free arrays for mfe folding * * @deprecated See vrna_fold(), vrna_circfold(), or vrna_mfe() and #vrna_fold_compound_t for the usage of the new API! * */ DEPRECATED(void free_arrays(void)); /** * @brief Recalculate energy parameters * * @deprecated For non-default model settings use the new API with vrna_params_subst() and vrna_mfe() instead! * */ DEPRECATED(void update_fold_params(void)); /** * @brief Recalculate energy parameters * * @deprecated For non-default model settings use the new API with vrna_params_subst() and vrna_mfe() instead! * */ DEPRECATED(void update_fold_params_par(vrna_param_t *parameters)); /** * * @deprecated See vrna_mfe() and #vrna_fold_compound_t for the usage of the new API! * */ DEPRECATED(void export_fold_arrays( int **f5_p, int **c_p, int **fML_p, int **fM1_p, int **indx_p, char **ptype_p)); /** * * @deprecated See vrna_mfe() and #vrna_fold_compound_t for the usage of the new API! * */ DEPRECATED(void export_fold_arrays_par( int **f5_p, int **c_p, int **fML_p, int **fM1_p, int **indx_p, char **ptype_p, vrna_param_t **P_p)); /** * * @deprecated See vrna_mfe() and #vrna_fold_compound_t for the usage of the new API! * */ DEPRECATED(void export_circfold_arrays( int *Fc_p, int *FcH_p, int *FcI_p, int *FcM_p, int **fM2_p, int **f5_p, int **c_p, int **fML_p, int **fM1_p, int **indx_p, char **ptype_p)); /** * * @deprecated See vrna_mfe() and #vrna_fold_compound_t for the usage of the new API! * */ DEPRECATED(void export_circfold_arrays_par( int *Fc_p, int *FcH_p, int *FcI_p, int *FcM_p, int **fM2_p, int **f5_p, int **c_p, int **fML_p, int **fM1_p, int **indx_p, char **ptype_p, vrna_param_t **P_p)); /* finally moved the loop energy function declarations to this header... */ /* BUT: The functions only exist for backward compatibility reasons! */ /* You better include "loop_energies.h" and call the functions: */ /* E_Hairpin() and E_IntLoop() which are (almost) threadsafe as they get */ /* a pointer to the energy parameter data structure as additional argument */ /** * @deprecated {This function is deprecated and will be removed soon. * Use @ref E_IntLoop() instead!} */ DEPRECATED(int LoopEnergy(int n1, int n2, int type, int type_2, int si1, int sj1, int sp1, int sq1)); /** * @deprecated {This function is deprecated and will be removed soon. * Use @ref E_Hairpin() instead!} */ DEPRECATED(int HairpinE(int size, int type, int si1, int sj1, const char *string)); /** * Allocate arrays for folding\n * @deprecated See vrna_mfe() and #vrna_fold_compound_t for the usage of the new API! * */ DEPRECATED(void initialize_fold(int length)); /** * */ DEPRECATED(char *backtrack_fold_from_pair(char *sequence, int i, int j)); #endif /** * @} */ #endif