1 #ifndef VIENNA_RNA_PACKAGE_ALIFOLD_H 2 #define VIENNA_RNA_PACKAGE_ALIFOLD_H 3 4 #include <ViennaRNA/datastructures/basic.h> 5 #include <ViennaRNA/params/basic.h> 6 #include <ViennaRNA/ribo.h> 7 #include <ViennaRNA/mfe.h> 8 #include <ViennaRNA/part_func.h> 9 #include <ViennaRNA/utils/alignments.h> 10 #include <ViennaRNA/utils/structures.h> 11 #include <ViennaRNA/boltzmann_sampling.h> 12 13 #ifdef VRNA_WARN_DEPRECATED 14 # if defined(__clang__) 15 # define DEPRECATED(func, msg) func __attribute__ ((deprecated("", msg))) 16 # elif defined(__GNUC__) 17 # define DEPRECATED(func, msg) func __attribute__ ((deprecated(msg))) 18 # else 19 # define DEPRECATED(func, msg) func 20 # endif 21 #else 22 # define DEPRECATED(func, msg) func 23 #endif 24 25 /** 26 * @file alifold.h 27 * @ingroup mfe_global_deprecated 28 * @brief Functions for comparative structure prediction using RNA sequence alignments 29 * 30 */ 31 32 #ifndef VRNA_DISABLE_BACKWARD_COMPATIBILITY 33 34 /* 35 ################################################# 36 # DEPRECATED FUNCTIONS # 37 ################################################# 38 */ 39 40 /** 41 * @ingroup mfe_global_deprecated 42 * @{ 43 */ 44 45 /** 46 * @brief Compute MFE and according consensus structure of an alignment of sequences 47 * 48 * This function predicts the consensus structure for the aligned 'sequences' 49 * and returns the minimum free energy; the mfe structure in bracket 50 * notation is returned in 'structure'. 51 * 52 * Sufficient space must be allocated for 'structure' before calling 53 * alifold(). 54 * 55 * @deprecated Usage of this function is discouraged! Use vrna_alifold(), or vrna_mfe() instead! 56 * @see vrna_alifold(), vrna_mfe() 57 * 58 * @param strings A pointer to a NULL terminated array of character arrays 59 * @param structure A pointer to a character array that may contain a constraining consensus structure 60 * (will be overwritten by a consensus structure that exhibits the MFE) 61 * @return The free energy score in kcal/mol 62 */ 63 DEPRECATED(float alifold( const char **strings, char *structure), 64 "Use vrna_alifold() or vrna_mfe() instead"); 65 66 /** 67 * @brief Compute MFE and according structure of an alignment of sequences assuming the sequences are circular instead of linear 68 * 69 * @deprecated Usage of this function is discouraged! Use vrna_alicircfold(), and vrna_mfe() instead! 70 * @see vrna_alicircfold(), vrna_alifold(), vrna_mfe() 71 * 72 * @param strings A pointer to a NULL terminated array of character arrays 73 * @param structure A pointer to a character array that may contain a constraining consensus structure 74 * (will be overwritten by a consensus structure that exhibits the MFE) 75 * @return The free energy score in kcal/mol 76 */ 77 DEPRECATED(float circalifold( const char **strings, char *structure), 78 "Use vrna_alicircfold() or vrna_mfe() instead"); 79 80 /** 81 * @brief Free the memory occupied by MFE alifold functions 82 * 83 * @deprecated Usage of this function is discouraged! It only 84 * affects memory being free'd that was allocated by an old API 85 * function before. Release of memory occupied by the newly introduced 86 * #vrna_fold_compound_t is handled by vrna_fold_compound_free() 87 * 88 * @see vrna_fold_compound_free() 89 * 90 */ 91 DEPRECATED(void free_alifold_arrays(void), 92 "This function is obsolete"); 93 94 /* End group mfe_global_deprecated */ 95 /**@}*/ 96 97 /** 98 * @brief Calculate the free energy of a consensus structure given a set of aligned sequences 99 * 100 * @ingroup consensus_fold 101 * 102 * @deprecated Usage of this function is discouraged! Use vrna_eval_structure(), and vrna_eval_covar_structure() instead! 103 * 104 * @param sequences The NULL terminated array of sequences 105 * @param structure The consensus structure 106 * @param n_seq The number of sequences in the alignment 107 * @param energy A pointer to an array of at least two floats that will hold the free energies 108 * (energy[0] will contain the free energy, energy[1] will be filled with the covariance energy term) 109 * @returns free energy in kcal/mol 110 * 111 */ 112 DEPRECATED(float energy_of_alistruct(const char **sequences, const char *structure, int n_seq, float *energy), 113 "Use vrna_eval_structure() and vrna_eval_covar_structure() instead"); 114 115 DEPRECATED(float energy_of_ali_gquad_structure(const char **sequences, const char *structure, int n_seq, float *energy), 116 "Use vrna_eval_structure() and vrna_eval_covar_structure() instead"); 117 118 /** 119 * @brief This variable controls the weight of the covariance term in the 120 * energy function of alignment folding algorithms 121 * 122 * @ingroup consensus_fold 123 * 124 * @deprecated See #vrna_md_t.cv_fact, and vrna_mfe() to avoid using global variables 125 * 126 * Default is 1. 127 */ 128 DEPRECATED(extern double cv_fact, 129 "Use the cv_fact attribute of the vrna_md_t datastructure instead"); 130 /** 131 * @brief This variable controls the magnitude of the penalty for non-compatible sequences in 132 * the covariance term of alignment folding algorithms. 133 * 134 * @ingroup consensus_fold 135 * 136 * @deprecated See #vrna_md_t.nc_fact, and vrna_mfe() to avoid using global variables 137 * 138 * Default is 1. 139 */ 140 DEPRECATED(extern double nc_fact, 141 "Use the nc_fact attribute of the vrna_md_t datastructure instead"); 142 143 /** 144 * @ingroup part_func_global_deprecated 145 * @{ 146 */ 147 148 /** 149 * @brief 150 * 151 * @deprecated Use vrna_pf() instead 152 * 153 * @param sequences 154 * @param structure 155 * @param pl 156 * @param parameters 157 * @param calculate_bppm 158 * @param is_constrained 159 * @param is_circular 160 * @return 161 */ 162 DEPRECATED(float alipf_fold_par( const char **sequences, 163 char *structure, 164 vrna_ep_t **pl, 165 vrna_exp_param_t *parameters, 166 int calculate_bppm, 167 int is_constrained, 168 int is_circular), 169 "Use vrna_pf_alifold() or vrna_pf() instead"); 170 171 /** 172 * @brief 173 * 174 * The partition function version of alifold() works in analogy to 175 * pf_fold(). Pair probabilities and information about sequence 176 * covariations are returned via the 'pi' variable as a list of 177 * #vrna_pinfo_t structs. The list is terminated by the first entry with 178 * pi.i = 0. 179 * 180 * @deprecated Use vrna_pf() instead 181 * 182 * @param sequences 183 * @param structure 184 * @param pl 185 * @return 186 */ 187 DEPRECATED(float alipf_fold( const char **sequences, char *structure, vrna_ep_t **pl), 188 "Use vrna_pf_alifold() or vrna_pf() instead"); 189 190 /** 191 * @brief 192 * 193 * @deprecated Use vrna_pf() instead 194 * 195 * @param sequences 196 * @param structure 197 * @param pl 198 * @return 199 */ 200 DEPRECATED(float alipf_circ_fold(const char **sequences, char *structure, vrna_ep_t **pl), 201 "Use vrna_pf_circalifold() or vrna_pf() instead"); 202 203 204 /** 205 * @brief Get a pointer to the base pair probability array 206 * 207 * Accessing the base pair probabilities for a pair (i,j) is achieved by 208 * @verbatim FLT_OR_DBL *pr = export_bppm(); pr_ij = pr[iindx[i]-j]; @endverbatim 209 * 210 * @deprecated Usage of this function is discouraged! The new #vrna_fold_compound_t 211 * allows direct access to the folding matrices, including the pair probabilities! 212 * The pair probability array returned here reflects the one of the latest call 213 * to vrna_pf(), or any of the old API calls for consensus structure 214 * partition function folding. 215 * 216 * @see #vrna_fold_compound_t, vrna_fold_compound_comparative(), and vrna_pf() 217 * 218 * @return A pointer to the base pair probability array 219 */ 220 DEPRECATED(FLT_OR_DBL *export_ali_bppm(void), 221 "Use the new API with vrna_fold_compound_t datastructure instead"); 222 223 /** 224 * @brief Free the memory occupied by folding matrices allocated by alipf_fold, alipf_circ_fold, etc. 225 * 226 * @deprecated Usage of this function is discouraged! This function only free's memory 227 * allocated by old API function calls. Memory allocated by any of the new API calls (starting with vrna_) 228 * will be not affected! 229 * 230 * @see #vrna_fold_compound_t, vrna_vrna_fold_compound_free() 231 * 232 */ 233 DEPRECATED(void free_alipf_arrays(void), 234 "This function is obsolete"); 235 236 /** 237 * @brief Sample a consensus secondary structure from the Boltzmann ensemble according its probability 238 * 239 * @deprecated Use vrna_pbacktrack() instead! 240 * 241 * @param prob to be described (berni) 242 * @return A sampled consensus secondary structure in dot-bracket notation 243 */ 244 DEPRECATED(char *alipbacktrack(double *prob), 245 "Use the new API and vrna_pbacktrack() instead"); 246 247 /** 248 * @brief Get pointers to (almost) all relavant arrays used in alifold's partition function computation 249 * 250 * @note To obtain meaningful pointers, call alipf_fold first! 251 * 252 * @see pf_alifold(), alipf_circ_fold() 253 * 254 * @deprecated It is discouraged to use this function! The new #vrna_fold_compound_t allows 255 * direct access to all necessary consensus structure prediction related variables! 256 * 257 * @see #vrna_fold_compound_t, vrna_fold_compound_comparative(), vrna_pf() 258 * 259 * @param S_p A pointer to the 'S' array (integer representation of nucleotides) 260 * @param S5_p A pointer to the 'S5' array 261 * @param S3_p A pointer to the 'S3' array 262 * @param a2s_p A pointer to the alignment-column to sequence position mapping array 263 * @param Ss_p A pointer to the 'Ss' array 264 * @param qb_p A pointer to the Q<sup>B</sup> matrix 265 * @param qm_p A pointer to the Q<sup>M</sup> matrix 266 * @param q1k_p A pointer to the 5' slice of the Q matrix (@f$q1k(k) = Q(1, k)@f$) 267 * @param qln_p A pointer to the 3' slice of the Q matrix (@f$qln(l) = Q(l, n)@f$) 268 * @param pscore A pointer to the start of a pscore list 269 * @return Non Zero if everything went fine, 0 otherwise 270 */ 271 DEPRECATED(int get_alipf_arrays(short ***S_p, 272 short ***S5_p, 273 short ***S3_p, 274 unsigned short ***a2s_p, 275 char ***Ss_p, 276 FLT_OR_DBL **qb_p, 277 FLT_OR_DBL **qm_p, 278 FLT_OR_DBL **q1k_p, 279 FLT_OR_DBL **qln_p, 280 short **pscore), 281 "Use the new API with vrna_fold_compound_t datastructure instead"); 282 283 284 /* End group part_func_global_deprecated */ 285 /**@}*/ 286 287 /** 288 * @brief Update the energy parameters for alifold function 289 * 290 * Call this to recalculate the pair matrix and energy parameters after a 291 * change in folding parameters like #temperature 292 * 293 * @ingroup consensus_fold 294 * @deprecated Usage of this function is discouraged! The new API uses #vrna_fold_compound_t 295 * to lump all folding related necessities together, including the energy parameters. Use 296 * vrna_update_fold_params() to update the energy parameters within a #vrna_fold_compound_t. 297 */ 298 DEPRECATED(void update_alifold_params(void), 299 "Use the new API with vrna_fold_compound_t datastructure instead"); 300 301 #endif 302 303 304 #endif 305