binaries/src/ViennaRNA/H/2Dpfold.h

   1 /*
   2       minimum free energy
   3       RNA secondary structure with
   4       basepair distance d to reference structure prediction
   5
   6 */
   7 #ifndef __VIENNA_RNA_PACKAGE_TWO_D_PF_FOLD_H__
   8 #define __VIENNA_RNA_PACKAGE_TWO_D_PF_FOLD_H__
   9
  10 #include "data_structures.h"
  11
  12 #ifdef __GNUC__
  13 #define DEPRECATED(func) func __attribute__ ((deprecated))
  14 #else
  15 #define DEPRECATED(func) func
  16 #endif
  17
  18 /**
  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
  22  *  @{
  23  *
  24  *  \file 2Dpfold.h
  25  */
  26
  27 /**
  28  * \brief Get a datastructure containing all necessary attributes and global folding switches
  29  *
  30  * This function prepares all necessary attributes and matrices etc which are needed for a call
  31  * of TwoDpfoldList.
  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.
  35  *
  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
  41  */
  42 TwoDpfold_vars  *get_TwoDpfold_variables( const char *seq,
  43                                           const char *structure1,
  44                                           char *structure2,
  45                                           int circ);
  46
  47 /**
  48  * \brief Get the datastructure containing all necessary attributes and global folding switches from
  49  * a pre-filled mfe-datastructure
  50  *
  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
  53  *
  54  * \see get_TwoDfold_variables(), get_TwoDpfold_variables()
  55  *
  56  * \param mfe_vars    the pre-filled mfe datastructure
  57  * \returns           the datastructure containing all necessary partition function attributes
  58  */
  59 TwoDpfold_vars  *get_TwoDpfold_variables_from_MFE(TwoDfold_vars *mfe_vars);
  60
  61 /**
  62  * \brief Free all memory occupied by a TwoDpfold_vars datastructure
  63  *
  64  * This function free's all memory occupied by a datastructure obtained from from
  65  * get_TwoDpfold_variables() or get_TwoDpfold_variables_from_MFE()
  66  *
  67  * \see get_TwoDpfold_variables(), get_TwoDpfold_variables_from_MFE()
  68  *
  69  * \param vars   the datastructure to be free'd
  70  */
  71 void            destroy_TwoDpfold_variables(TwoDpfold_vars *vars);
  72
  73 /**
  74  * \brief Compute the partition function for all distance classes
  75  *
  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
  84  * the restriction.
  85  * A values of #INF in the attribute 'k' of the returned list denotes the end of the list
  86  *
  87  * \see get_TwoDpfold_variables(), destroy_TwoDpfold_variables(), #TwoDpfold_solution
  88  *
  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
  93  */
  94 TwoDpfold_solution  *TwoDpfoldList( TwoDpfold_vars *vars,
  95                                     int maxDistance1,
  96                                     int maxDistance2);
  97
  98 /** @} */ /* End of group kl_neighborhood_pf */
  99
 100 /**
 101  *  \addtogroup kl_neighborhood_stochbt
 102  *  \brief Contains functions related to stochastic backtracking from a specified distance class
 103  *  @{
 104  */
 105
 106 /**
 107  *  \brief Sample secondary structure representatives from a set of distance classes according to their
 108  *  Boltzmann probability
 109  *
 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.
 112  *
 113  *  \pre      The argument 'vars' must contain precalculated partition function matrices,
 114  *            i.e. a call to TwoDpfoldList() preceding this function is mandatory!
 115  *
 116  *  \see      TwoDpfoldList()
 117  *
 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
 122  */
 123 char            *TwoDpfold_pbacktrack(TwoDpfold_vars *vars,
 124                                       int d1,
 125                                       int d2);
 126
 127 /**
 128  * \brief Sample secondary structure representatives with a specified length from a set of distance classes according to their
 129  *  Boltzmann probability
 130  *
 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
 133  *
 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!
 137  *
 138  * \see       TwoDpfold_pbacktrack(), TwoDpfoldList()
 139  *
 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
 145  */
 146 char            *TwoDpfold_pbacktrack5( TwoDpfold_vars *vars,
 147                                           int d1,
 148                                           int d2,
 149                                           unsigned int length);
 150
 151 /** @} */ /* End of group kl_neighborhood_stochbt */
 152
 153 /**
 154  * \brief
 155  *
 156  *
 157  */
 158 DEPRECATED(FLT_OR_DBL          **TwoDpfold(TwoDpfold_vars *our_variables,
 159                                 int maxDistance1,
 160                                 int maxDistance2));
 161
 162 /**
 163  * \brief
 164  *
 165  *
 166  */
 167 DEPRECATED(FLT_OR_DBL          **TwoDpfold_circ(
 168                                 TwoDpfold_vars *our_variables,
 169                                 int maxDistance1,
 170                                 int maxDistance2));
 171
 172
 173 #endif