# Direct Refolding Paths between two Secondary Structures

Heuristics to explore direct, optimal (re-)folding paths between two secondary structures.

  Functions

  int vrna_path_findpath_saddle(vrna_fold_compound_t *fc, const char *s1, const char *s2, int width)
    #include <ViennaRNA/landscape/findpath.h>

    Find energy of a saddle point between 2 structures (search only direct path)

    This function uses an inplementation of the findpath algorithm [Flamm et al., 2001] for near-optimal direct refolding path prediction.

    Model details, and energy parameters are used as provided via the parameter ‘fc’. The vrna_fold_compound_t does not require memory for any DP matrices, but requires all most basic init values as one would get from a call like this:

        fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_DEFAULT);

    SWIG Wrapper Notes:

      This function is attached as an overloaded method `path_findpath_saddle()` to objects of type `fold_compound`. The optional parameter `width` defaults to 1 if it is omitted. See, e.g. `RNA.fold_compound.path_findpath_saddle()` in the Python API.

    See also

    vrna_path_findpath_saddle_ub(), vrna_fold_compound(), vrna_fold_compound_t, vrna_path_findpath()

    Parameters:

      - fc – The vrna_fold_compound_t with precomputed sequence encoding and model details

      - s1 – The start structure in dot-bracket notation

      - s2 – The target structure in dot-bracket notation

      - width – A number specifying how many strutures are being kept at each step during the search

    Returns:

      The saddle energy in 10cal/mol

  int vrna_path_findpath_saddle_ub(vrna_fold_compound_t *fc, const char *s1, const char *s2, int width, int maxE)
    #include <ViennaRNA/landscape/findpath.h>

    Find energy of a saddle point between 2 structures (search only direct path)

    This function uses an inplementation of the findpath algorithm [Flamm et al., 2001] for near-optimal direct refolding path prediction.

    Model details, and energy parameters are used as provided via the parameter ‘fc’. The vrna_fold_compound_t does not require memory for any DP matrices, but requires all most basic init values as one would get from a call like this:

        fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_DEFAULT);

    SWIG Wrapper Notes:

      This function is attached as an overloaded method `path_findpath_saddle()` to objects of type `fold_compound`. The optional parameter `width` defaults to 1 if it is omitted, while the optional parameter `maxE` defaults to INF. In case the function did not find a path with \(E_{saddle} < E_{max}\) the function returns a `NULL` object, i.e. `undef` for Perl and `None` for Python. See, e.g. `RNA.fold_compound.path_findpath_saddle()` in the Python API.

    See also

    vrna_path_findpath_saddle(), vrna_fold_compound(), vrna_fold_compound_t, vrna_path_findpath()

    Warning

    The argument `maxE` ( \(E_{max}\)) enables one to specify an upper bound, or maximum free energy for the saddle point between the two input structures. If no path with \(E_{saddle} < E_{max}\) is found, the function simply returns `maxE`

    Parameters:

      - fc – The vrna_fold_compound_t with precomputed sequence encoding and model details

      - s1 – The start structure in dot-bracket notation

      - s2 – The target structure in dot-bracket notation

      - width – A number specifying how many strutures are being kept at each step during the search

      - maxE – An upper bound for the saddle point energy in 10cal/mol

    Returns:

      The saddle energy in 10cal/mol

  vrna_path_t *vrna_path_findpath(vrna_fold_compound_t *fc, const char *s1, const char *s2, int width)
    #include <ViennaRNA/landscape/findpath.h>

    Find refolding path between 2 structures (search only direct path)

    This function uses an inplementation of the findpath algorithm [Flamm et al., 2001] for near-optimal direct refolding path prediction.

    Model details, and energy parameters are used as provided via the parameter ‘fc’. The vrna_fold_compound_t does not require memory for any DP matrices, but requires all most basic init values as one would get from a call like this:

        fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_DEFAULT);

    SWIG Wrapper Notes:

      This function is attached as an overloaded method `path_findpath()` to objects of type `fold_compound`. The optional parameter `width` defaults to 1 if it is omitted. See, e.g. `RNA.fold_compound.path_findpath()` in the Python API.

    See also

    vrna_path_findpath_ub(), vrna_fold_compound(), vrna_fold_compound_t, vrna_path_findpath_saddle()

    Parameters:

      - fc – The vrna_fold_compound_t with precomputed sequence encoding and model details

      - s1 – The start structure in dot-bracket notation

      - s2 – The target structure in dot-bracket notation

      - width – A number specifying how many strutures are being kept at each step during the search

    Returns:

      The saddle energy in 10cal/mol

  vrna_path_t *vrna_path_findpath_ub(vrna_fold_compound_t *fc, const char *s1, const char *s2, int width, int maxE)
    #include <ViennaRNA/landscape/findpath.h>

    Find refolding path between 2 structures (search only direct path)

    This function uses an inplementation of the findpath algorithm [Flamm et al., 2001] for near-optimal direct refolding path prediction.

    Model details, and energy parameters are used as provided via the parameter ‘fc’. The vrna_fold_compound_t does not require memory for any DP matrices, but requires all most basic init values as one would get from a call like this:

        fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_DEFAULT);

    SWIG Wrapper Notes:

      This function is attached as an overloaded method `path_findpath()` to objects of type `fold_compound`. The optional parameter `width` defaults to 1 if it is omitted, while the optional parameter `maxE` defaults to INF. In case the function did not find a path with \(E_{saddle} < E_{max}\) the function returns an empty list. See, e.g. `RNA.fold_compound.path_findpath()` in the Python API.

    See also

    vrna_path_findpath(), vrna_fold_compound(), vrna_fold_compound_t, vrna_path_findpath_saddle()

    Warning

    The argument `maxE` enables one to specify an upper bound, or maximum free energy for the saddle point between the two input structures. If no path with \(E_{saddle} < E_{max}\) is found, the function simply returns NULL

    Parameters:

      - fc – The vrna_fold_compound_t with precomputed sequence encoding and model details

      - s1 – The start structure in dot-bracket notation

      - s2 – The target structure in dot-bracket notation

      - width – A number specifying how many strutures are being kept at each step during the search

      - maxE – An upper bound for the saddle point energy in 10cal/mol

    Returns:

      The saddle energy in 10cal/mol

  vrna_path_options_t vrna_path_options_findpath(int width, unsigned int type)
    #include <ViennaRNA/landscape/paths.h>

    Create options data structure for findpath direct (re-)folding path heuristic.

    This function returns an options data structure that switches the vrna_path_direct() and vrna_path_direct_ub() API functions to use the findpath [Flamm et al., 2001] heuristic. The parameter `width` specifies the width of the breadth-first search while the second parameter `type` allows one to set the type of the returned (re-)folding path.

    Currently, the following return types are available:

    - A list of dot-bracket structures and corresponding free energy (flag: VRNA_PATH_TYPE_DOT_BRACKET)

    - A list of transition moves and corresponding free energy changes (flag: VRNA_PATH_TYPE_MOVES)

    SWIG Wrapper Notes:

      This function is available as overloaded function `path_options_findpath()`. The optional parameter `width` defaults to 10 if omitted, while the optional parameter `type` defaults to VRNA_PATH_TYPE_DOT_BRACKET. See, e.g. `RNA.path_options_findpath()` in the Python API.

    See also

    VRNA_PATH_TYPE_DOT_BRACKET, VRNA_PATH_TYPE_MOVES, vrna_path_options_free(), vrna_path_direct(), vrna_path_direct_ub()

    Parameters:

      - width – Width of the breath-first search strategy

      - type – Setting that specifies how the return (re-)folding path should be encoded

    Returns:

      An options data structure with settings for the findpath direct path heuristic

  vrna_path_t *vrna_path_direct(vrna_fold_compound_t *fc, const char *s1, const char *s2, vrna_path_options_t options)
    #include <ViennaRNA/landscape/paths.h>

    Determine an optimal direct (re-)folding path between two secondary structures.

    This is the generic wrapper function to retrieve (an optimal) (re-)folding path between two secondary structures `s1` and `s2`. The actual algorithm that is used to generate the (re-)folding path is determined by the settings specified in the `options` data structure. This data structure also determines the return type, which might be either:

    - a list of dot-bracket structures with corresponding free energy, or

    - a list of transition moves with corresponding free energy change

    If the `options` parameter is passed a NULL pointer, this function defaults to the findpath heuristic [Flamm et al., 2001] with a breadth-first search width of \( 10 \), and the returned path consists of dot-bracket structures with corresponding free energies.

    SWIG Wrapper Notes:

      This function is attached as an overloaded method `path_direct()` to objects of type `fold_compound`. The optional parameter `options` defaults to `NULL` if it is omitted. See, e.g. `RNA.fold_compound.path_direct()` in the Python API.

    See also

    vrna_path_direct_ub(), vrna_path_options_findpath(), vrna_path_options_free(), vrna_path_free()

    Parameters:

      - fc – The vrna_fold_compound_t with precomputed sequence encoding and model details

      - s1 – The start structure in dot-bracket notation

      - s2 – The target structure in dot-bracket notation

      - options – An options data structure that specifies the path heuristic and corresponding settings (maybe NULL)

    Returns:

      An optimal (re-)folding path between the two input structures

  vrna_path_t *vrna_path_direct_ub(vrna_fold_compound_t *fc, const char *s1, const char *s2, int maxE, vrna_path_options_t options)
    #include <ViennaRNA/landscape/paths.h>

    Determine an optimal direct (re-)folding path between two secondary structures.

    This function is similar to vrna_path_direct(), but allows to specify an upper-bound for the saddle point energy. The underlying algorithms will stop determining an (optimal) (re-)folding path, if none can be found that has a saddle point below the specified upper-bound threshold `maxE`.

    SWIG Wrapper Notes:

      This function is attached as an overloaded method `path_direct()` to objects of type `fold_compound`. The optional parameter `maxE` defaults to #INT_MAX - 1 if it is omitted, while the optional parameter `options` defaults to `NULL`. In case the function did not find a path with \(E_{saddle} < E_{max}\) it returns an empty list. See, e.g. `RNA.fold_compound.path_direct()` in the Python API.

    See also

    vrna_path_direct_ub(), vrna_path_options_findpath(), vrna_path_options_free(), vrna_path_free()

    Warning

    The argument `maxE` enables one to specify an upper bound, or maximum free energy for the saddle point between the two input structures. If no path with \(E_{saddle} < E_{max}\) is found, the function simply returns NULL

    Parameters:

      - fc – The vrna_fold_compound_t with precomputed sequence encoding and model details

      - s1 – The start structure in dot-bracket notation

      - s2 – The target structure in dot-bracket notation

      - maxE – Upper bound for the saddle point along the (re-)folding path

      - options – An options data structure that specifies the path heuristic and corresponding settings (maybe NULL)

    Returns:

      An optimal (re-)folding path between the two input structures