#ifndef VIENNA_RNA_PACKAGE_ALIFOLD_H #define VIENNA_RNA_PACKAGE_ALIFOLD_H /* make this interface backward compatible with RNAlib < 2.2.0 */ #define VRNA_BACKWARD_COMPAT #include #include #include #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 /** * @file alifold.h * @ingroup consensus_fold * @brief Functions for comparative structure prediction using RNA sequence alignments * */ /* ############################################## # MFE VARIANTS OF THE ALIFOLD IMPLEMENTATION # ############################################## */ /** * @brief Compute Minimum Free Energy (MFE), and a corresponding consensus secondary structure * for an RNA sequence alignment using a comparative method * * @ingroup consensus_mfe_fold * * This simplified interface to vrna_mfe() computes the MFE and, if required, a consensus secondary * structure for an RNA sequence alignment 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_circalifold(), vrna_mfe(), vrna_fold_compound(), #vrna_fold_compound_t * * @param sequences RNA sequence alignment * @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_alifold( const char **sequences, char *structure); /** * @brief Compute Minimum Free Energy (MFE), and a corresponding consensus secondary structure * for a sequence alignment of circular RNAs using a comparative method * * @ingroup consensus_mfe_fold * * This simplified interface to vrna_mfe() computes the MFE and, if required, a consensus secondary * structure for an RNA sequence alignment 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_alifold(), vrna_mfe(), vrna_fold_compound(), #vrna_fold_compound_t * * @param sequences Sequence alignment of circular RNAs * @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_circalifold( const char **sequences, char *structure); /* ############################################################# # PARTITION FUNCTION VARIANTS OF THE ALIFOLD IMPLEMENTATION # ############################################################# */ /** * @brief Compute Partition function @f$Q@f$ (and base pair probabilities) for an RNA * sequence alignment using a comparative method * * @ingroup consensus_pf_fold * * This simplified interface to vrna_pf() computes the partition function and, if required, * base pair probabilities for an RNA sequence alignment 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. * * @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_pf(), * and the data structure #vrna_fold_compound_t instead. * * @see vrna_pf_circalifold(), vrna_pf(), vrna_fold_compound_comparative(), #vrna_fold_compound_t * * @param sequences RNA sequence alignment * @param structure A pointer to the character array where position-wise pairing propensity * will be stored. (Maybe NULL) * @param pl A pointer to a list of #vrna_plist_t to store pairing probabilities (Maybe NULL) * @return The Gibbs free energy of the ensemble (@f$G = -RT \cdot \log(Q) @f$) in kcal/mol */ float vrna_pf_alifold(const char **sequences, char *structure, vrna_plist_t **pl); /** * @brief Compute Partition function @f$Q@f$ (and base pair probabilities) for an alignment * of circular RNA sequences using a comparative method * * @ingroup consensus_pf_fold * * This simplified interface to vrna_pf() computes the partition function and, if required, * base pair probabilities for an RNA sequence alignment 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. * * @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_pf(), * and the data structure #vrna_fold_compound_t instead. * * Folding of circular RNA sequences is handled as a post-processing step of the forward * recursions. See @cite hofacker:2006 for further details. * * @see vrna_pf_alifold(), vrna_pf(), vrna_fold_compound_comparative(), #vrna_fold_compound_t * * @param sequences Sequence alignment of circular RNAs * @param structure A pointer to the character array where position-wise pairing propensity * will be stored. (Maybe NULL) * @param pl A pointer to a list of #vrna_plist_t to store pairing probabilities (Maybe NULL) * @return The Gibbs free energy of the ensemble (@f$G = -RT \cdot \log(Q) @f$) in kcal/mol */ float vrna_pf_circalifold(const char **sequences, char *structure, vrna_plist_t **pl); #ifdef VRNA_BACKWARD_COMPAT /* ################################################# # DEPRECATED FUNCTIONS # ################################################# */ /** * @brief Compute MFE and according consensus structure of an alignment of sequences * * This function predicts the consensus structure for the aligned 'sequences' * and returns the minimum free energy; the mfe structure in bracket * notation is returned in 'structure'. * * Sufficient space must be allocated for 'structure' before calling * alifold(). * * @ingroup consensus_mfe_fold * * @deprecated Usage of this function is discouraged! Use vrna_alifold(), or vrna_mfe() instead! * @see vrna_alifold(), vrna_mfe() * * @param strings A pointer to a NULL terminated array of character arrays * @param structure A pointer to a character array that may contain a constraining consensus structure * (will be overwritten by a consensus structure that exhibits the MFE) * @return The free energy score in kcal/mol */ DEPRECATED(float alifold( const char **strings, char *structure)); /** * @brief Compute MFE and according structure of an alignment of sequences assuming the sequences are circular instead of linear * * @ingroup consensus_mfe_fold * * @deprecated Usage of this function is discouraged! Use vrna_alicircfold(), and vrna_mfe() instead! * @see vrna_alicircfold(), vrna_alifold(), vrna_mfe() * * @param strings A pointer to a NULL terminated array of character arrays * @param structure A pointer to a character array that may contain a constraining consensus structure * (will be overwritten by a consensus structure that exhibits the MFE) * @return The free energy score in kcal/mol */ DEPRECATED(float circalifold( const char **strings, char *structure)); /** * @brief Free the memory occupied by MFE alifold functions * * @deprecated Usage of this function is discouraged! It only * affects memory being free'd that was allocated by an old API * function before. Release of memory occupied by the newly introduced * #vrna_fold_compound_t is handled by vrna_vrna_fold_compound_free() * * @see vrna_vrna_fold_compound_free() * * @ingroup consensus_mfe_fold * */ DEPRECATED(void free_alifold_arrays(void)); /** * @brief Calculate the free energy of a consensus structure given a set of aligned sequences * * @ingroup consensus_fold * * @deprecated Usage of this function is discouraged! Use vrna_eval_structure(), and vrna_eval_covar_structure() instead! * * @param sequences The NULL terminated array of sequences * @param structure The consensus structure * @param n_seq The number of sequences in the alignment * @param energy A pointer to an array of at least two floats that will hold the free energies * (energy[0] will contain the free energy, energy[1] will be filled with the covariance energy term) * @returns free energy in kcal/mol * */ DEPRECATED(float energy_of_alistruct(const char **sequences, const char *structure, int n_seq, float *energy)); DEPRECATED(float energy_of_ali_gquad_structure(const char **sequences, const char *structure, int n_seq, float *energy)); /** * @brief This variable controls the weight of the covariance term in the * energy function of alignment folding algorithms * * @ingroup consensus_fold * * @deprecated See #vrna_md_t.cv_fact, and vrna_mfe() to avoid using global variables * * Default is 1. */ DEPRECATED(extern double cv_fact); /** * @brief This variable controls the magnitude of the penalty for non-compatible sequences in * the covariance term of alignment folding algorithms. * * @ingroup consensus_fold * * @deprecated See #vrna_md_t.nc_fact, and vrna_mfe() to avoid using global variables * * Default is 1. */ DEPRECATED(extern double nc_fact); /** * @brief * * @ingroup consensus_pf_fold * * @deprecated Use vrna_pf() instead * * @param sequences * @param structure * @param pl * @param parameters * @param calculate_bppm * @param is_constrained * @param is_circular * @return */ DEPRECATED(float alipf_fold_par( const char **sequences, char *structure, vrna_plist_t **pl, vrna_exp_param_t *parameters, int calculate_bppm, int is_constrained, int is_circular)); /** * @brief * * The partition function version of alifold() works in analogy to * pf_fold(). Pair probabilities and information about sequence * covariations are returned via the 'pi' variable as a list of * #vrna_pinfo_t structs. The list is terminated by the first entry with * pi.i = 0. * * @ingroup consensus_pf_fold * * @deprecated Use vrna_pf() instead * * @param sequences * @param structure * @param pl * @return */ DEPRECATED(float alipf_fold( const char **sequences, char *structure, vrna_plist_t **pl)); /** * @brief * * @ingroup consensus_pf_fold * * @deprecated Use vrna_pf() instead * * @param sequences * @param structure * @param pl * @return */ DEPRECATED(float alipf_circ_fold(const char **sequences, char *structure, vrna_plist_t **pl)); /** * @brief Get a pointer to the base pair probability array * * Accessing the base pair probabilities for a pair (i,j) is achieved by * @verbatim FLT_OR_DBL *pr = export_bppm(); pr_ij = pr[iindx[i]-j]; @endverbatim * * @ingroup consensus_pf_fold * * @deprecated Usage of this function is discouraged! The new #vrna_fold_compound_t * allows direct access to the folding matrices, including the pair probabilities! * The pair probability array returned here reflects the one of the latest call * to vrna_pf(), or any of the old API calls for consensus structure * partition function folding. * * @see #vrna_fold_compound_t, vrna_fold_compound_comparative(), and vrna_pf() * * @return A pointer to the base pair probability array */ DEPRECATED(FLT_OR_DBL *export_ali_bppm(void)); /** * @brief Free the memory occupied by folding matrices allocated by alipf_fold, alipf_circ_fold, etc. * * @ingroup consensus_pf_fold * * @deprecated Usage of this function is discouraged! This function only free's memory * allocated by old API function calls. Memory allocated by any of the new API calls (starting with vrna_) * will be not affected! * * @see #vrna_fold_compound_t, vrna_vrna_fold_compound_free() * */ DEPRECATED(void free_alipf_arrays(void)); /** * @brief Sample a consensus secondary structure from the Boltzmann ensemble according its probability * * @ingroup consensus_stochbt * * @deprecated Use vrna_pbacktrack() instead! * * @param prob to be described (berni) * @return A sampled consensus secondary structure in dot-bracket notation */ DEPRECATED(char *alipbacktrack(double *prob)); /** * @brief Get pointers to (almost) all relavant arrays used in alifold's partition function computation * * @ingroup consensus_fold * * @note To obtain meaningful pointers, call alipf_fold first! * * @see pf_alifold(), alipf_circ_fold() * * @deprecated It is discouraged to use this function! The new #vrna_fold_compound_t allows * direct access to all necessary consensus structure prediction related variables! * * @see #vrna_fold_compound_t, vrna_fold_compound_comparative(), vrna_pf() * * @param S_p A pointer to the 'S' array (integer representation of nucleotides) * @param S5_p A pointer to the 'S5' array * @param S3_p A pointer to the 'S3' array * @param a2s_p A pointer to the pair type matrix * @param Ss_p A pointer to the 'Ss' array * @param qb_p A pointer to the QB matrix * @param qm_p A pointer to the QM matrix * @param q1k_p A pointer to the 5' slice of the Q matrix (@f$q1k(k) = Q(1, k)@f$) * @param qln_p A pointer to the 3' slice of the Q matrix (@f$qln(l) = Q(l, n)@f$) * @param pscore A pointer to the start of a pscore list * @return Non Zero if everything went fine, 0 otherwise */ DEPRECATED(int get_alipf_arrays(short ***S_p, short ***S5_p, short ***S3_p, unsigned short ***a2s_p, char ***Ss_p, FLT_OR_DBL **qb_p, FLT_OR_DBL **qm_p, FLT_OR_DBL **q1k_p, FLT_OR_DBL **qln_p, short **pscore)); /** * @brief Update the energy parameters for alifold function * * Call this to recalculate the pair matrix and energy parameters after a * change in folding parameters like #temperature * * @ingroup consensus_fold * @deprecated Usage of this function is discouraged! The new API uses #vrna_fold_compound_t * to lump all folding related necessities together, including the energy parameters. Use * vrna_update_fold_params() to update the energy parameters within a #vrna_fold_compound_t. */ DEPRECATED(void update_alifold_params(void)); #endif #endif