# Distance Based Partitioning of the Secondary Structure Space

The secondary structure space is divided into partitions according to the base pair distance to two given reference structures and all relevant properties are calculated for each of the resulting partitions.

See also…

For further details, we refer to Lorenz et al. [2009]

## General

## MFE Variants

Compute the minimum free energy (MFE) and secondary structures for a partitioning of the secondary structure space according to the base pair distance to two fixed reference structures basepair distance to two fixed reference structures.

  Defines

  TwoDfold_solution
    #include <ViennaRNA/2Dfold.h>

  Functions

  vrna_sol_TwoD_t *vrna_mfe_TwoD(vrna_fold_compound_t *fc, int distance1, int distance2)
    #include <ViennaRNA/2Dfold.h>

    Compute MFE’s and representative for distance partitioning.

    This function computes the minimum free energies and a representative secondary structure for each distance class according to the two references specified in the datastructure ‘vars’. The maximum basepair distance to each of both references may be set by the arguments ‘distance1’ and ‘distance2’, respectively. If both distance arguments are set to ‘-1’, no restriction is assumed and the calculation is performed for each distance class possible.

    The returned list contains an entry for each distance class. If a maximum basepair distance to either of the references was passed, an entry with k=l=-1 will be appended in the list, denoting the class where all structures exceeding the maximum will be thrown into. The end of the list is denoted by an attribute value of INF in the k-attribute of the list entry.

    See also

    vrna_fold_compound_TwoD(), vrna_fold_compound_free(), vrna_pf_TwoD() vrna_backtrack5_TwoD(), vrna_sol_TwoD_t, vrna_fold_compound_t

    Parameters:

      - fc – The datastructure containing all precomputed folding attributes

      - distance1 – maximum distance to reference1 (-1 means no restriction)

      - distance2 – maximum distance to reference2 (-1 means no restriction)

    Returns:

      A list of minimum free energies (and corresponding structures) for each distance class

  char *vrna_backtrack5_TwoD(vrna_fold_compound_t *fc, int k, int l, unsigned int j)
    #include <ViennaRNA/2Dfold.h>

    Backtrack a minimum free energy structure from a 5’ section of specified length.

    This function allows one to backtrack a secondary structure beginning at the 5’ end, a specified length and residing in a specific distance class. If the argument ‘k’ gets a value of -1, the structure that is backtracked is assumed to reside in the distance class where all structures exceeding the maximum basepair distance specified in vrna_mfe_TwoD() belong to.

    See also

    vrna_mfe_TwoD()

    Note

    The argument ‘vars’ must contain precalculated energy values in the energy matrices, i.e. a call to vrna_mfe_TwoD() preceding this function is mandatory!

    Parameters:

      - fc – The datastructure containing all precomputed folding attributes

      - j – The length in nucleotides beginning from the 5’ end

      - k – distance to reference1 (may be -1)

      - l – distance to reference2

  TwoDfold_vars *get_TwoDfold_variables(const char *seq, const char *structure1, const char *structure2, int circ)
    #include <ViennaRNA/2Dfold.h>

    Get a structure of type TwoDfold_vars prefilled with current global settings.

    This function returns a datastructure of type TwoDfold_vars. The data fields inside the TwoDfold_vars are prefilled by global settings and all memory allocations necessary to start a computation are already done for the convenience of the user

    Deprecated:

      Use the new API that relies on vrna_fold_compound_t and the corresponding functions vrna_fold_compound_TwoD(), vrna_mfe_TwoD(), and vrna_fold_compound_free() instead!

    Note

    Make sure that the reference structures are compatible with the sequence according to Watson-Crick- and Wobble-base pairing

    Parameters:

      - seq – The RNA sequence

      - structure1 – The first reference structure in dot-bracket notation

      - structure2 – The second reference structure in dot-bracket notation

      - circ – A switch to indicate the assumption to fold a circular instead of linear RNA (0=OFF, 1=ON)

    Returns:

      A datastructure prefilled with folding options and allocated memory

  void destroy_TwoDfold_variables(TwoDfold_vars *our_variables)
    #include <ViennaRNA/2Dfold.h>

    Destroy a TwoDfold_vars datastructure without memory loss.

    This function free’s all allocated memory that depends on the datastructure given.

    Deprecated:

      Use the new API that relies on vrna_fold_compound_t and the corresponding functions vrna_fold_compound_TwoD(), vrna_mfe_TwoD(), and vrna_fold_compound_free() instead!

    Parameters:

      - our_variables – A pointer to the datastructure to be destroyed

  TwoDfold_solution *TwoDfoldList(TwoDfold_vars *vars, int distance1, int distance2)
    #include <ViennaRNA/2Dfold.h>

    Compute MFE’s and representative for distance partitioning.

    This function computes the minimum free energies and a representative secondary structure for each distance class according to the two references specified in the datastructure ‘vars’. The maximum basepair distance to each of both references may be set by the arguments ‘distance1’ and ‘distance2’, respectively. If both distance arguments are set to ‘-1’, no restriction is assumed and the calculation is performed for each distance class possible.

    The returned list contains an entry for each distance class. If a maximum basepair distance to either of the references was passed, an entry with k=l=-1 will be appended in the list, denoting the class where all structures exceeding the maximum will be thrown into. The end of the list is denoted by an attribute value of INF in the k-attribute of the list entry.

    Deprecated:

      Use the new API that relies on vrna_fold_compound_t and the corresponding functions vrna_fold_compound_TwoD(), vrna_mfe_TwoD(), and vrna_fold_compound_free() instead!

    Parameters:

      - vars – the datastructure containing all predefined folding attributes

      - distance1 – maximum distance to reference1 (-1 means no restriction)

      - distance2 – maximum distance to reference2 (-1 means no restriction)

  char *TwoDfold_backtrack_f5(unsigned int j, int k, int l, TwoDfold_vars *vars)
    #include <ViennaRNA/2Dfold.h>

    Backtrack a minimum free energy structure from a 5’ section of specified length.

    This function allows one to backtrack a secondary structure beginning at the 5’ end, a specified length and residing in a specific distance class. If the argument ‘k’ gets a value of -1, the structure that is backtracked is assumed to reside in the distance class where all structures exceeding the maximum basepair distance specified in TwoDfold() belong to.

    Deprecated:

      Use the new API that relies on vrna_fold_compound_t and the corresponding functions vrna_fold_compound_TwoD(), vrna_mfe_TwoD(), vrna_backtrack5_TwoD(), and vrna_fold_compound_free() instead!

    Note

    The argument ‘vars’ must contain precalculated energy values in the energy matrices, i.e. a call to TwoDfold() preceding this function is mandatory!

    Parameters:

      - j – The length in nucleotides beginning from the 5’ end

      - k – distance to reference1 (may be -1)

      - l – distance to reference2

      - vars – the datastructure containing all predefined folding attributes

  TwoDfold_solution **TwoDfold(TwoDfold_vars *our_variables, int distance1, int distance2)
    #include <ViennaRNA/2Dfold.h>
  struct vrna_sol_TwoD_t
    #include <ViennaRNA/2Dfold.h>

    Solution element returned from vrna_mfe_TwoD()

    This element contains free energy and structure for the appropriate kappa (k), lambda (l) neighborhood The datastructure contains two integer attributes ‘k’ and ‘l’ as well as an attribute ‘en’ of type float representing the free energy in kcal/mol and an attribute ‘s’ of type char* containg the secondary structure representative,

    A value of INF in k denotes the end of a list

    See also

    vrna_mfe_TwoD()

    Public Members

    int k

      Distance to first reference.

    int l

      Distance to second reference.

    float en

      Free energy in kcal/mol.

    char *s

      MFE representative structure in dot-bracket notation.

  struct TwoDfold_vars
    #include <ViennaRNA/2Dfold.h>

    Variables compound for 2Dfold MFE folding.

    Deprecated:

      This data structure will be removed from the library soon! Use vrna_fold_compound_t and the corresponding functions vrna_fold_compound_TwoD(), vrna_mfe_TwoD(), and vrna_fold_compound_free() instead!

    Public Members

    vrna_param_t *P

      Precomputed energy parameters and model details.

    int do_backtrack

      Flag whether to do backtracing of the structure(s) or not.

    char *ptype

      Precomputed array of pair types.

    char *sequence

      The input sequence

    short *S
    short *S1

      The input sequences in numeric form.

    unsigned int maxD1

      Maximum allowed base pair distance to first reference.

    unsigned int maxD2

      Maximum allowed base pair distance to second reference.

    unsigned int *mm1

      Maximum matching matrix, reference struct 1 disallowed.

    unsigned int *mm2

      Maximum matching matrix, reference struct 2 disallowed.

    int *my_iindx

      Index for moving in quadratic distancy dimensions.

    double temperature
    unsigned int *referenceBPs1

      Matrix containing number of basepairs of reference structure1 in interval [i,j].

    unsigned int *referenceBPs2

      Matrix containing number of basepairs of reference structure2 in interval [i,j].

    unsigned int *bpdist

      Matrix containing base pair distance of reference structure 1 and 2 on interval [i,j].

    short *reference_pt1
    short *reference_pt2
    int circ
    int dangles
    unsigned int seq_length
    int ***E_F5
    int ***E_F3
    int ***E_C
    int ***E_M
    int ***E_M1
    int ***E_M2
    int **E_Fc
    int **E_FcH
    int **E_FcI
    int **E_FcM
    int **l_min_values
    int **l_max_values
    int *k_min_values
    int *k_max_values
    int **l_min_values_m
    int **l_max_values_m
    int *k_min_values_m
    int *k_max_values_m
    int **l_min_values_m1
    int **l_max_values_m1
    int *k_min_values_m1
    int *k_max_values_m1
    int **l_min_values_f
    int **l_max_values_f
    int *k_min_values_f
    int *k_max_values_f
    int **l_min_values_f3
    int **l_max_values_f3
    int *k_min_values_f3
    int *k_max_values_f3
    int **l_min_values_m2
    int **l_max_values_m2
    int *k_min_values_m2
    int *k_max_values_m2
    int *l_min_values_fc
    int *l_max_values_fc
    int k_min_values_fc
    int k_max_values_fc
    int *l_min_values_fcH
    int *l_max_values_fcH
    int k_min_values_fcH
    int k_max_values_fcH
    int *l_min_values_fcI
    int *l_max_values_fcI
    int k_min_values_fcI
    int k_max_values_fcI
    int *l_min_values_fcM
    int *l_max_values_fcM
    int k_min_values_fcM
    int k_max_values_fcM
    int *E_F5_rem
    int *E_F3_rem
    int *E_C_rem
    int *E_M_rem
    int *E_M1_rem
    int *E_M2_rem
    int E_Fc_rem
    int E_FcH_rem
    int E_FcI_rem
    int E_FcM_rem
    vrna_fold_compound_t *compatibility

## Partition Function Variants

Compute the partition function and stochastically sample secondary structures for a partitioning of the secondary structure space according to the base pair distance to two fixed reference structures.

  Functions

  vrna_sol_TwoD_pf_t *vrna_pf_TwoD(vrna_fold_compound_t *fc, int maxDistance1, int maxDistance2)
    #include <ViennaRNA/2Dpfold.h>

    Compute the partition function for all distance classes.

    This function computes the partition functions for all distance classes according the two reference structures specified in the datastructure ‘vars’. Similar to vrna_mfe_TwoD() the arguments maxDistance1 and maxDistance2 specify the maximum distance to both reference structures. A value of ‘-1’ in either of them makes the appropriate distance restrictionless, i.e. all basepair distancies to the reference are taken into account during computation. In case there is a restriction, the returned solution contains an entry where the attribute k=l=-1 contains the partition function for all structures exceeding the restriction. A value of INF in the attribute ‘k’ of the returned list denotes the end of the list

    See also

    vrna_fold_compound_TwoD(), vrna_fold_compound_free(), vrna_fold_compound vrna_sol_TwoD_pf_t

    Parameters:

      - fc – The datastructure containing all necessary folding attributes and matrices

      - maxDistance1 – The maximum basepair distance to reference1 (may be -1)

      - maxDistance2 – The maximum basepair distance to reference2 (may be -1)

    Returns:

      A list of partition funtions for the corresponding distance classes

  struct vrna_sol_TwoD_pf_t
    #include <ViennaRNA/2Dpfold.h>

    Solution element returned from vrna_pf_TwoD()

    This element contains the partition function for the appropriate kappa (k), lambda (l) neighborhood The datastructure contains two integer attributes ‘k’ and ‘l’ as well as an attribute ‘q’ of type FLT_OR_DBL

    A value of INF in k denotes the end of a list

    See also

    vrna_pf_TwoD()

    Public Members

    int k

      Distance to first reference.

    int l

      Distance to second reference.

    FLT_OR_DBL q

      partition function

## Stochastic Backtracking

Functions related to stochastic backtracking from a specified distance class.

  Functions

  char *vrna_pbacktrack_TwoD(vrna_fold_compound_t *fc, int d1, int d2)
    #include <ViennaRNA/2Dpfold.h>

    Sample secondary structure representatives from a set of distance classes according to their Boltzmann probability.

    If the argument ‘d1’ is set to ‘-1’, the structure will be backtracked in the distance class where all structures exceeding the maximum basepair distance to either of the references reside.

    See also

    vrna_pf_TwoD()

    Parameters:

      - fc – [inout] The vrna_fold_compound_t datastructure containing all necessary folding attributes and matrices

      - d1 – [in] The distance to reference1 (may be -1)

      - d2 – [in] The distance to reference2

    Pre:

      The argument ‘vars’ must contain precalculated partition function matrices, i.e. a call to vrna_pf_TwoD() preceding this function is mandatory!

    Returns:

      A sampled secondary structure in dot-bracket notation

  char *vrna_pbacktrack5_TwoD(vrna_fold_compound_t *fc, int d1, int d2, unsigned int length)
    #include <ViennaRNA/2Dpfold.h>

    Sample secondary structure representatives with a specified length from a set of distance classes according to their Boltzmann probability.

    This function does essentially the same as vrna_pbacktrack_TwoD() with the only difference that partial structures, i.e. structures beginning from the 5’ end with a specified length of the sequence, are backtracked

    See also

    vrna_pbacktrack_TwoD(), vrna_pf_TwoD()

    Note

    This function does not work (since it makes no sense) for circular RNA sequences!

    Parameters:

      - fc – [inout] The vrna_fold_compound_t datastructure containing all necessary folding attributes and matrices

      - d1 – [in] The distance to reference1 (may be -1)

      - d2 – [in] The distance to reference2

      - length – [in] The length of the structure beginning from the 5’ end

    Pre:

      The argument ‘vars’ must contain precalculated partition function matrices, i.e. a call to vrna_pf_TwoD() preceding this function is mandatory!

    Returns:

      A sampled secondary structure in dot-bracket notation