binaries/src/ViennaRNA/H/2Dfold.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_FOLD_H__
   8 #define __VIENNA_RNA_PACKAGE_TWO_D_FOLD_H__
   9
  10 /**
  11  *  \addtogroup kl_neighborhood
  12  *  \brief Compute Thermodynamic properties for a Distance Class Partitioning of the Secondary Structure Space
  13  *
  14  *  All functions related to this group implement the basic recursions for MFE folding, partition function
  15  *  computation and stochastic backtracking with a \e classified \e dynamic \e programming approach.
  16  *  The secondary structure space is divided into partitions according to the base pair distance to two
  17  *  given reference structures and all relevant properties are calculated for each of the resulting partitions
  18  *  \see  For further details have a look into \cite lorenz:2009
  19  */
  20
  21 /**
  22  *  \addtogroup kl_neighborhood_mfe
  23  *  \brief Compute the minimum free energy (MFE) and secondary structures for a partitioning of
  24  *  the secondary structure space according to the base pair distance to two fixed reference structures
  25  *  basepair distance to two fixed reference structures
  26  *  @{
  27  *
  28  *  \file 2Dfold.h
  29  *
  30  */
  31
  32 #include "data_structures.h"
  33
  34 #ifdef __GNUC__
  35 #define DEPRECATED(func) func __attribute__ ((deprecated))
  36 #else
  37 #define DEPRECATED(func) func
  38 #endif
  39
  40 /**
  41  *  \brief Get a structure of type TwoDfold_vars prefilled with current global settings
  42  *
  43  *  This function returns a datastructure of type TwoDfold_vars.
  44  *  The data fields inside the TwoDfold_vars are prefilled by global settings and all memory
  45  *  allocations necessary to start a computation are already done for the convenience of the user
  46  *
  47  *  \note Make sure that the reference structures are compatible with the sequence according to Watson-Crick- and Wobble-base pairing
  48  *
  49  *  \see destroy_TwoDfold_variables(), TwoDfold(), TwoDfold_circ
  50  *
  51  *  \param seq          The RNA sequence
  52  *  \param structure1   The first reference structure in dot-bracket notation
  53  *  \param structure2   The second reference structure in dot-bracket notation
  54  *  \param circ         A switch to indicate the assumption to fold a circular instead of linear RNA (0=OFF, 1=ON)
  55  *  \returns            A datastructure prefilled with folding options and allocated memory
  56  */
  57 TwoDfold_vars *get_TwoDfold_variables(const char *seq,
  58                                       const char *structure1,
  59                                       const char *structure2,
  60                                       int circ);
  61
  62 /**
  63  *  \brief Destroy a TwoDfold_vars datastructure without memory loss
  64  *
  65  *  This function free's all allocated memory that depends on the datastructure given.
  66  *
  67  *  \see get_TwoDfold_variables()
  68  *
  69  *  \param our_variables  A pointer to the datastructure to be destroyed
  70  */
  71 void          destroy_TwoDfold_variables(TwoDfold_vars *our_variables);
  72
  73 /**
  74  *
  75  */
  76 DEPRECATED(TwoDfold_solution **TwoDfold(TwoDfold_vars *our_variables,
  77                                         int distance1,
  78                                         int distance2));
  79
  80 /**
  81  * \brief Compute MFE's and representative for distance partitioning
  82  *
  83  * This function computes the minimum free energies and a representative
  84  * secondary structure for each distance class according to the two references
  85  * specified in the datastructure 'vars'.
  86  * The maximum basepair distance to each of both references may be set
  87  * by the arguments 'distance1' and 'distance2', respectively.
  88  * If both distance arguments are set to '-1', no restriction is assumed and
  89  * the calculation is performed for each distance class possible.
  90  *
  91  * The returned list contains an entry for each distance class. If a maximum
  92  * basepair distance to either of the references was passed, an entry with
  93  * k=l=-1 will be appended in the list, denoting the class where all structures
  94  * exceeding the maximum will be thrown into.
  95  * The end of the list is denoted by an attribute value of #INF in
  96  * the k-attribute of the list entry.
  97  *
  98  * \see get_TwoDfold_variables(), destroy_TwoDfold_variables(), #TwoDfold_solution
  99  *
 100  * \param vars      the datastructure containing all predefined folding attributes
 101  * \param distance1 maximum distance to reference1 (-1 means no restriction)
 102  * \param distance2 maximum distance to reference2 (-1 means no restriction)
 103  */
 104 TwoDfold_solution *TwoDfoldList(TwoDfold_vars *vars,
 105                                 int distance1,
 106                                 int distance2);
 107
 108 /**
 109  * \brief Backtrack a minimum free energy structure from a 5' section of specified length
 110  *
 111  * This function allows to backtrack a secondary structure beginning at the 5' end, a specified
 112  * length and residing in a specific distance class.
 113  * If the argument 'k' gets a value of -1, the structure that is backtracked is assumed to
 114  * reside in the distance class where all structures exceeding the maximum basepair distance
 115  * specified in TwoDfoldList() belong to.
 116  * \note The argument 'vars' must contain precalculated energy values in the energy matrices,
 117  * i.e. a call to TwoDfoldList() preceding this function is mandatory!
 118  *
 119  * \see TwoDfoldList(), get_TwoDfold_variables(), destroy_TwoDfold_variables()
 120  *
 121  * \param j     The length in nucleotides beginning from the 5' end
 122  * \param k     distance to reference1 (may be -1)
 123  * \param l     distance to reference2
 124  * \param vars  the datastructure containing all predefined folding attributes
 125  */
 126 char *TwoDfold_backtrack_f5(unsigned int j,
 127                             int k,
 128                             int l,
 129                             TwoDfold_vars *vars);
 130
 131 /**
 132  *  @}
 133  */
 134 #endif