3 RNA secondary structure with
4 basepair distance d to reference structure prediction
7 #ifndef __VIENNA_RNA_PACKAGE_TWO_D_PF_FOLD_H__
8 #define __VIENNA_RNA_PACKAGE_TWO_D_PF_FOLD_H__
10 #include "data_structures.h"
13 #define DEPRECATED(func) func __attribute__ ((deprecated))
15 #define DEPRECATED(func) func
19 * \addtogroup kl_neighborhood_pf
20 * \brief Compute the partition function and stochastically sample secondary structures for a partitioning of
21 * the secondary structure space according to the base pair distance to two fixed reference structures
28 * \brief Get a datastructure containing all necessary attributes and global folding switches
30 * This function prepares all necessary attributes and matrices etc which are needed for a call
32 * A snapshot of all current global model switches (dangles, temperature and so on) is done and
33 * stored in the returned datastructure. Additionally, all matrices that will hold the partition
34 * function values are prepared.
36 * \param seq the RNA sequence in uppercase format with letters from the alphabet {AUCG}
37 * \param structure1 the first reference structure in dot-bracket notation
38 * \param structure2 the second reference structure in dot-bracket notation
39 * \param circ a switch indicating if the sequence is linear (0) or circular (1)
40 * \returns the datastructure containing all necessary partition function attributes
42 TwoDpfold_vars *get_TwoDpfold_variables( const char *seq,
43 const char *structure1,
48 * \brief Get the datastructure containing all necessary attributes and global folding switches from
49 * a pre-filled mfe-datastructure
51 * This function actually does the same as get_TwoDpfold_variables but takes its switches and
52 * settings from a pre-filled MFE equivalent datastructure
54 * \see get_TwoDfold_variables(), get_TwoDpfold_variables()
56 * \param mfe_vars the pre-filled mfe datastructure
57 * \returns the datastructure containing all necessary partition function attributes
59 TwoDpfold_vars *get_TwoDpfold_variables_from_MFE(TwoDfold_vars *mfe_vars);
62 * \brief Free all memory occupied by a TwoDpfold_vars datastructure
64 * This function free's all memory occupied by a datastructure obtained from from
65 * get_TwoDpfold_variables() or get_TwoDpfold_variables_from_MFE()
67 * \see get_TwoDpfold_variables(), get_TwoDpfold_variables_from_MFE()
69 * \param vars the datastructure to be free'd
71 void destroy_TwoDpfold_variables(TwoDpfold_vars *vars);
74 * \brief Compute the partition function for all distance classes
76 * This function computes the partition functions for all distance classes
77 * according the two reference structures specified in the datastructure 'vars'.
78 * Similar to TwoDfoldList() the arguments maxDistance1 and maxDistance2 specify
79 * the maximum distance to both reference structures. A value of '-1' in either of
80 * them makes the appropriate distance restrictionless, i.e. all basepair distancies
81 * to the reference are taken into account during computation.
82 * In case there is a restriction, the returned solution contains an entry where
83 * the attribute k=l=-1 contains the partition function for all structures exceeding
85 * A values of #INF in the attribute 'k' of the returned list denotes the end of the list
87 * \see get_TwoDpfold_variables(), destroy_TwoDpfold_variables(), #TwoDpfold_solution
89 * \param vars the datastructure containing all necessary folding attributes and matrices
90 * \param maxDistance1 the maximum basepair distance to reference1 (may be -1)
91 * \param maxDistance2 the maximum basepair distance to reference2 (may be -1)
92 * \returns a list of partition funtions for the appropriate distance classes
94 TwoDpfold_solution *TwoDpfoldList( TwoDpfold_vars *vars,
98 /** @} */ /* End of group kl_neighborhood_pf */
101 * \addtogroup kl_neighborhood_stochbt
102 * \brief Contains functions related to stochastic backtracking from a specified distance class
107 * \brief Sample secondary structure representatives from a set of distance classes according to their
108 * Boltzmann probability
110 * If the argument 'd1' is set to '-1', the structure will be backtracked in the distance class
111 * where all structures exceeding the maximum basepair distance to either of the references reside.
113 * \pre The argument 'vars' must contain precalculated partition function matrices,
114 * i.e. a call to TwoDpfoldList() preceding this function is mandatory!
116 * \see TwoDpfoldList()
118 * \param[in] vars the datastructure containing all necessary folding attributes and matrices
119 * \param[in] d1 the distance to reference1 (may be -1)
120 * \param[in] d2 the distance to reference2
121 * \returns A sampled secondary structure in dot-bracket notation
123 char *TwoDpfold_pbacktrack(TwoDpfold_vars *vars,
128 * \brief Sample secondary structure representatives with a specified length from a set of distance classes according to their
129 * Boltzmann probability
131 * This function does essentially the same as TwoDpfold_pbacktrack with the only difference that partial structures,
132 * i.e. structures beginning from the 5' end with a specified length of the sequence, are backtracked
134 * \note This function does not work (since it makes no sense) for circular RNA sequences!
135 * \pre The argument 'vars' must contain precalculated partition function matrices,
136 * i.e. a call to TwoDpfoldList() preceding this function is mandatory!
138 * \see TwoDpfold_pbacktrack(), TwoDpfoldList()
140 * \param[in] vars the datastructure containing all necessary folding attributes and matrices
141 * \param[in] d1 the distance to reference1 (may be -1)
142 * \param[in] d2 the distance to reference2
143 * \param[in] length the length of the structure beginning from the 5' end
144 * \returns A sampled secondary structure in dot-bracket notation
146 char *TwoDpfold_pbacktrack5( TwoDpfold_vars *vars,
149 unsigned int length);
151 /** @} */ /* End of group kl_neighborhood_stochbt */
158 DEPRECATED(FLT_OR_DBL **TwoDpfold(TwoDpfold_vars *our_variables,
167 DEPRECATED(FLT_OR_DBL **TwoDpfold_circ(
168 TwoDpfold_vars *our_variables,