--- /dev/null
+#ifndef __VIENNA_RNA_PACKAGE_FOLD_H__
+#define __VIENNA_RNA_PACKAGE_FOLD_H__
+
+#include "data_structures.h"
+
+#ifdef __GNUC__
+#define DEPRECATED(func) func __attribute__ ((deprecated))
+#else
+#define DEPRECATED(func) func
+#endif
+
+/**
+ * \addtogroup mfe_fold
+ * \ingroup folding_routines
+ * \brief This section covers all functions and variables related to the calculation
+ * of minimum free energy (MFE) structures.
+ *
+ * The library provides a fast dynamic programming minimum free energy
+ * folding algorithm as described in \cite zuker:1981.
+ * All relevant parts that directly implement the "Zuker & Stiegler" algorithm for single
+ * sequences are described in this section.
+ *
+ * Folding of circular RNA sequences is handled as a post-processing step of the forward
+ * recursions. See \cite hofacker:2006 for further details.
+ *
+ * Nevertheless, the RNAlib also
+ * provides interfaces for the prediction of consensus MFE structures of sequence alignments,
+ * MFE structure for two hybridized sequences, local optimal structures and many more. For
+ * those more specialized variants of MFE folding routines, please consult the appropriate
+ * subsections (Modules) as listed above.
+ *
+ * \file fold.h
+ * \brief MFE calculations and energy evaluations for single RNA sequences
+ *
+ * This file includes (almost) all function declarations within the RNAlib that are related to
+ * MFE folding...
+ */
+
+/**
+ * \defgroup eval Energy evaluation
+ * @{
+ * \brief This module contains all functions and variables related to energy evaluation
+ * of sequence/structure pairs.
+ *
+ *
+ * @}
+ */
+
+/**
+ * \defgroup mfe_fold Calculating Minimum Free Energy Structures
+ * @{
+ * \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 \ref zuker_81 "Zuker & Stiegler (1981)".
+ * @}
+ */
+
+/** \brief if nonzero use logarithmic ML energy in energy_of_struct */
+extern int logML;
+
+/** \brief do ML decomposition uniquely (for subopt) */
+extern int uniq_ML;
+
+/** \brief set to first pos of second seq for cofolding */
+extern int cut_point;
+
+/**
+ * \brief verbose info from energy_of_struct
+ * \ingroup eval
+ */
+extern int eos_debug;
+
+
+/**
+ * \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
+ *
+ * \ingroup mfe_fold
+ *
+ * \see fold(), circfold(), #model_detailsT, 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 prescaled energy contributions
+ * and the model details. (NULL may be passed, see OpenMP notes above)
+ * \param is_constrained Switch to indicate that a structure contraint is passed via the structure argument (0==off)
+ * \param is_circular Switch to (de-)activate postprocessing steps in case RNA sequence is circular (0==off)
+ *
+ * \return the minimum free energy (MFE) in kcal/mol
+ */
+float fold_par( const char *sequence,
+ char *structure,
+ paramT *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
+ *
+ * Use fold_par() for a completely threadsafe variant
+ *
+ * \ingroup mfe_fold
+ *
+ * \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
+ */
+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
+ *
+ * Use fold_par() for a completely threadsafe variant
+ *
+ * \ingroup mfe_fold
+ *
+ * \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
+ */
+float circfold( const char *sequence,
+ char *structure);
+
+
+/**
+ * \addtogroup eval Energy evaluation
+ * \ingroup folding_routines
+ * @{
+ * \brief This module contains all functions and variables related to energy evaluation
+ * of sequence/structure pairs.
+ * @}
+ */
+
+/**
+ * \brief Calculate the free energy of an already folded RNA using global model detail settings
+ *
+ * If verbosity level is set to a value >0, energies of structure elements are printed to stdout
+ *
+ * \note OpenMP: This function relies on several global model settings variables and thus is
+ * not to be considered threadsafe. See energy_of_struct_par() for a completely threadsafe
+ * implementation.
+ *
+ * \ingroup eval
+ *
+ * \see energy_of_struct_par(), energy_of_circ_structure()
+ *
+ * \param string RNA sequence
+ * \param structure secondary structure in dot-bracket notation
+ * \param verbosity_level a flag to turn verbose output on/off
+ * \return the free energy of the input structure given the input sequence in kcal/mol
+ */
+float energy_of_structure(const char *string,
+ const char *structure,
+ int verbosity_level);
+
+/**
+ * \brief Calculate the free energy of an already folded RNA
+ *
+ * If verbosity level is set to a value >0, energies of structure elements are printed to stdout
+ *
+ * \ingroup eval
+ *
+ * \see energy_of_circ_structure(), energy_of_structure_pt(), get_scaled_parameters()
+ *
+ * \param string RNA sequence in uppercase letters
+ * \param structure Secondary structure in dot-bracket notation
+ * \param parameters A data structure containing the prescaled energy contributions and the model details.
+ * \param verbosity_level A flag to turn verbose output on/off
+ * \return The free energy of the input structure given the input sequence in kcal/mol
+ */
+float energy_of_struct_par( const char *string,
+ const char *structure,
+ paramT *parameters,
+ int verbosity_level);
+
+/**
+ * \brief Calculate the free energy of an already folded circular RNA
+ *
+ * \note OpenMP: This function relies on several global model settings variables and thus is
+ * not to be considered threadsafe. See energy_of_circ_struct_par() for a completely threadsafe
+ * implementation.
+ *
+ * If verbosity level is set to a value >0, energies of structure elements are printed to stdout
+ *
+ * \ingroup eval
+ *
+ * \see energy_of_circ_struct_par(), energy_of_struct_par()
+ *
+ * \param string RNA sequence
+ * \param structure Secondary structure in dot-bracket notation
+ * \param verbosity_level A flag to turn verbose output on/off
+ * \return The free energy of the input structure given the input sequence in kcal/mol
+ */
+float energy_of_circ_structure( const char *string,
+ const char *structure,
+ int verbosity_level);
+
+/**
+ * \brief Calculate the free energy of an already folded circular RNA
+ *
+ * If verbosity level is set to a value >0, energies of structure elements are printed to stdout
+ *
+ * \ingroup eval
+ *
+ * \see energy_of_struct_par(), get_scaled_parameters()
+ *
+ * \param string RNA sequence
+ * \param structure Secondary structure in dot-bracket notation
+ * \param parameters A data structure containing the prescaled energy contributions and the model details.
+ * \param verbosity_level A flag to turn verbose output on/off
+ * \return The free energy of the input structure given the input sequence in kcal/mol
+ */
+float energy_of_circ_struct_par(const char *string,
+ const char *structure,
+ paramT *parameters,
+ int verbosity_level);
+
+
+float energy_of_gquad_structure(const char *string,
+ const char *structure,
+ int verbosity_level);
+
+/**
+ * \brief Calculate the free energy of an already folded RNA
+ *
+ * If verbosity level is set to a value >0, energies of structure elements are printed to stdout
+ *
+ * \note OpenMP: This function relies on several global model settings variables and thus is
+ * not to be considered threadsafe. See energy_of_struct_pt_par() for a completely threadsafe
+ * implementation.
+ *
+ * \ingroup eval
+ *
+ * \see make_pair_table(), energy_of_struct_pt_par()
+ *
+ * \param string RNA sequence
+ * \param ptable the pair table of the secondary structure
+ * \param s encoded RNA sequence
+ * \param s1 encoded RNA sequence
+ * \param verbosity_level a flag to turn verbose output on/off
+ * \return the free energy of the input structure given the input sequence in 10kcal/mol
+ */
+int energy_of_structure_pt( const char *string,
+ short *ptable,
+ short *s,
+ short *s1,
+ int verbosity_level);
+
+/**
+ * \brief Calculate the free energy of an already folded RNA
+ *
+ * If verbosity level is set to a value >0, energies of structure elements are printed to stdout
+ *
+ * \ingroup eval
+ *
+ * \see make_pair_table(), energy_of_struct_par(), get_scaled_parameters()
+ *
+ * \param string RNA sequence in uppercase letters
+ * \param ptable The pair table of the secondary structure
+ * \param s Encoded RNA sequence
+ * \param s1 Encoded RNA sequence
+ * \param parameters A data structure containing the prescaled energy contributions and the model details.
+ * \param verbosity_level A flag to turn verbose output on/off
+ * \return The free energy of the input structure given the input sequence in 10kcal/mol
+ */
+int energy_of_struct_pt_par(const char *string,
+ short *ptable,
+ short *s,
+ short *s1,
+ paramT *parameters,
+ int verbosity_level);
+
+/**
+ * \brief Free arrays for mfe folding
+ *
+ * \ingroup mfe_fold
+ *
+ */
+void free_arrays(void);
+
+
+/**
+ * \brief Create a dot-backet/parenthesis structure from backtracking stack
+ *
+ * \note This function is threadsafe
+ */
+void parenthesis_structure(char *structure,
+ bondT *bp,
+ int length);
+
+/**
+ * \brief Create a dot-backet/parenthesis structure from backtracking stack
+ * obtained by zuker suboptimal calculation in cofold.c
+ *
+ * \note This function is threadsafe
+ */
+void parenthesis_zuker( char *structure,
+ bondT *bp,
+ int length);
+
+void letter_structure(char *structure,
+ bondT *bp,
+ int length);
+
+
+/**
+ * \brief Recalculate energy parameters
+ *
+ * \ingroup mfe_fold
+ */
+void update_fold_params(void);
+
+/**
+ *
+ * \ingroup mfe_fold
+ *
+ */
+void update_fold_params_par(paramT *parameters);
+
+/**
+ *
+ * \ingroup mfe_fold
+ *
+ */
+char *backtrack_fold_from_pair(char *sequence,
+ int i,
+ int j);
+
+/**
+ * \brief Calculate energy of a move (closing or opening of a base pair)
+ *
+ * If the parameters m1 and m2 are negative, it is deletion (opening)
+ * of a base pair, otherwise it is insertion (opening).
+ *
+ * \see make_pair_table(), energy_of_move()
+ * \param string RNA sequence
+ * \param structure secondary structure in dot-bracket notation
+ * \param m1 first coordinate of base pair
+ * \param m2 second coordinate of base pair
+ * \returns energy change of the move in kcal/mol
+ */
+float energy_of_move( const char *string,
+ const char *structure,
+ int m1,
+ int m2);
+
+
+/**
+ *
+ * \brief Calculate energy of a move (closing or opening of a base pair)
+ *
+ * If the parameters m1 and m2 are negative, it is deletion (opening)
+ * of a base pair, otherwise it is insertion (opening).
+ *
+ * \see make_pair_table(), energy_of_move()
+ * \param pt the pair table of the secondary structure
+ * \param s encoded RNA sequence
+ * \param s1 encoded RNA sequence
+ * \param m1 first coordinate of base pair
+ * \param m2 second coordinate of base pair
+ * \returns energy change of the move in 10cal/mol
+ */
+int energy_of_move_pt(short *pt,
+ short *s,
+ short *s1,
+ int m1,
+ int m2);
+
+/**
+ * \brief Calculate energy of a loop
+ *
+ * \param ptable the pair table of the secondary structure
+ * \param s encoded RNA sequence
+ * \param s1 encoded RNA sequence
+ * \param i position of covering base pair
+ * \returns free energy of the loop in 10cal/mol
+ */
+int loop_energy(short *ptable,
+ short *s,
+ short *s1,
+ int i);
+
+/**
+ *
+ * \ingroup mfe_fold
+ *
+ */
+void export_fold_arrays(int **f5_p,
+ int **c_p,
+ int **fML_p,
+ int **fM1_p,
+ int **indx_p,
+ char **ptype_p);
+
+/**
+ *
+ * \ingroup mfe_fold
+ *
+ */
+void export_fold_arrays_par(int **f5_p,
+ int **c_p,
+ int **fML_p,
+ int **fM1_p,
+ int **indx_p,
+ char **ptype_p,
+ paramT **P_p);
+
+/**
+ *
+ * \ingroup mfe_fold
+ *
+ */
+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);
+
+/**
+ *
+ * \ingroup mfe_fold
+ *
+ */
+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,
+ paramT **P_p);
+
+
+/**
+ * \brief Create a plist from a dot-bracket string
+ *
+ * The dot-bracket string is parsed and for each base pair an
+ * entry in the plist is created. The probability of each pair in
+ * the list is set by a function parameter.
+ *
+ * The end of the plist is marked by sequence positions i as well as j
+ * equal to 0. This condition should be used to stop looping over its
+ * entries
+ *
+ * This function is threadsafe
+ *
+ * \param pl A pointer to the plist that is to be created
+ * \param struc The secondary structure in dot-bracket notation
+ * \param pr The probability for each base pair
+ */
+void assign_plist_from_db(plist **pl,
+ const char *struc,
+ float pr);
+
+/* 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 datastructure 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 {This function is deprecated and will be removed soon!}
+ *
+ */
+DEPRECATED(void initialize_fold(int length));
+
+/**
+ * Calculate the free energy of an already folded RNA
+ *
+ * \note This function is not entirely threadsafe! Depending on the state of the global
+ * variable \ref eos_debug it prints energy information to stdout or not...\n
+ *
+ * \deprecated This function is deprecated and should not be used in future programs!
+ * Use \ref energy_of_structure() instead!
+ *
+ * \see energy_of_structure, energy_of_circ_struct(), energy_of_struct_pt()
+ * \param string RNA sequence
+ * \param structure secondary structure in dot-bracket notation
+ * \return the free energy of the input structure given the input sequence in kcal/mol
+ */
+DEPRECATED(float energy_of_struct(const char *string,
+ const char *structure));
+
+/**
+ * Calculate the free energy of an already folded RNA
+ *
+ * \note This function is not entirely threadsafe! Depending on the state of the global
+ * variable \ref eos_debug it prints energy information to stdout or not...\n
+ *
+ * \deprecated This function is deprecated and should not be used in future programs!
+ * Use \ref energy_of_structure_pt() instead!
+ *
+ * \see make_pair_table(), energy_of_structure()
+ * \param string RNA sequence
+ * \param ptable the pair table of the secondary structure
+ * \param s encoded RNA sequence
+ * \param s1 encoded RNA sequence
+ * \return the free energy of the input structure given the input sequence in 10kcal/mol
+ */
+DEPRECATED(int energy_of_struct_pt( const char *string,
+ short *ptable,
+ short *s,
+ short *s1));
+
+/**
+ * Calculate the free energy of an already folded circular RNA
+ *
+ * \note This function is not entirely threadsafe! Depending on the state of the global
+ * variable \ref eos_debug it prints energy information to stdout or not...\n
+ *
+ * \deprecated This function is deprecated and should not be used in future programs
+ * Use \ref energy_of_circ_structure() instead!
+ *
+ * \see energy_of_circ_structure(), energy_of_struct(), energy_of_struct_pt()
+ * \param string RNA sequence
+ * \param structure secondary structure in dot-bracket notation
+ * \return the free energy of the input structure given the input sequence in kcal/mol
+ */
+DEPRECATED(float energy_of_circ_struct( const char *string,
+ const char *structure));
+
+#endif
git://source.jalview.org / jabaws.git / blobdiff