Local (sliding window) Partition Function and Equilibrium Probabilities — ViennaRNA Package

# Local (sliding window) Partition Function and Equilibrium Probabilities

Scanning version using a sliding window approach to compute equilibrium probabilities.

  Basic local partition function interface

  int vrna_probs_window(vrna_fold_compound_t *fc, int ulength, unsigned int options, vrna_probs_window_f cb, void *data)

    Compute various equilibrium probabilities under a sliding window approach.

        #include <ViennaRNA/partfunc/local.h>

    This function applies a sliding window scan for the sequence provided with the argument `fc` and reports back equilibrium probabilities through the callback function `cb`. The data reported to the callback depends on the `options` flag.

    Options:

    - VRNA_PROBS_WINDOW_BPP - Trigger base pairing probabilities.

    - VRNA_PROBS_WINDOW_UP - Trigger unpaired probabilities.

    - VRNA_PROBS_WINDOW_UP_SPLIT - Trigger detailed unpaired probabilities split up into different loop type contexts.

    Options may be OR-ed together

    See also

    vrna_pfl_fold_cb(), vrna_pfl_fold_up_cb()

    Note

    The parameter `ulength` only affects computation and resulting data if unpaired probability computations are requested through the `options` flag.

    Parameters:

      - fc – The fold compound with sequence data, model settings and precomputed energy parameters

      - ulength – The maximal length of an unpaired segment (only for unpaired probability computations)

      - cb – The callback function which collects the pair probability data for further processing

      - data – Some arbitrary data structure that is passed to the callback `cb`

      - options – Option flags to control the behavior of this function

    Returns:

      0 on failure, non-zero on success

  Simplified global partition function computation using sequence(s) or multiple sequence alignment(s)

  vrna_ep_t *vrna_pfl_fold(const char *sequence, int window_size, int max_bp_span, float cutoff)

    Compute base pair probabilities using a sliding-window approach.

        #include <ViennaRNA/partfunc/local.h>

    This is a simplified wrapper to vrna_probs_window() that given a nucleid acid sequence, a window size, a maximum base pair span, and a cutoff value computes the pair probabilities for any base pair in any window. The pair probabilities are returned as a list and the user has to take care to free() the memory occupied by the list.

    See also

    vrna_probs_window(), vrna_pfl_fold_cb(), vrna_pfl_fold_up()

    Note

    This function uses default model settings! For custom model settings, we refer to the function vrna_probs_window()

    .

    In case of any computation errors, this function returns

    `NULL`
    Parameters:

      - sequence – The nucleic acid input sequence

      - window_size – The size of the sliding window

      - max_bp_span – The maximum distance along the backbone between two nucleotides that form a base pairs

      - cutoff – A cutoff value that omits all pairs with lower probability

    Returns:

      A list of base pair probabilities, terminated by an entry with vrna_ep_t.i and vrna_ep_t.j set to 0

  int vrna_pfl_fold_cb(const char *sequence, int window_size, int max_bp_span, vrna_probs_window_f cb, void *data)

    Compute base pair probabilities using a sliding-window approach (callback version).

        #include <ViennaRNA/partfunc/local.h>

    This is a simplified wrapper to vrna_probs_window() that given a nucleid acid sequence, a window size, a maximum base pair span, and a cutoff value computes the pair probabilities for any base pair in any window. It is similar to vrna_pfl_fold() but uses a callback mechanism to return the pair probabilities.

    Read the details for vrna_probs_window() for details on the callback implementation!

    See also

    vrna_probs_window(), vrna_pfl_fold(), vrna_pfl_fold_up_cb()

    Note

    This function uses default model settings! For custom model settings, we refer to the function vrna_probs_window().

    Parameters:

      - sequence – The nucleic acid input sequence

      - window_size – The size of the sliding window

      - max_bp_span – The maximum distance along the backbone between two nucleotides that form a base pairs

      - cb – The callback function which collects the pair probability data for further processing

      - data – Some arbitrary data structure that is passed to the callback `cb`

    Returns:

      0 on failure, non-zero on success

  double **vrna_pfl_fold_up(const char *sequence, int ulength, int window_size, int max_bp_span)

    Compute probability of contiguous unpaired segments.

        #include <ViennaRNA/partfunc/local.h>

    This is a simplified wrapper to vrna_probs_window() that given a nucleic acid sequence, a maximum length of unpaired segments (`ulength`), a window size, and a maximum base pair span computes the equilibrium probability of any segment not exceeding `ulength`. The probabilities to be unpaired are returned as a 1-based, 2-dimensional matrix with dimensions \( N \times M \), where \(N\) is the length of the sequence and \(M\) is the maximum segment length. As an example, the probability of a segment of size 5 starting at position 100 is stored in the matrix entry \(X[100][5]\).

    It is the users responsibility to free the memory occupied by this matrix.

    Note

    This function uses default model settings! For custom model settings, we refer to the function vrna_probs_window().

    Parameters:

      - sequence – The nucleic acid input sequence

      - ulength – The maximal length of an unpaired segment

      - window_size – The size of the sliding window

      - max_bp_span – The maximum distance along the backbone between two nucleotides that form a base pairs

    Returns:

      The probabilities to be unpaired for any segment not exceeding `ulength`

  int vrna_pfl_fold_up_cb(const char *sequence, int ulength, int window_size, int max_bp_span, vrna_probs_window_f cb, void *data)

    Compute probability of contiguous unpaired segments.

        #include <ViennaRNA/partfunc/local.h>

    This is a simplified wrapper to vrna_probs_window() that given a nucleic acid sequence, a maximum length of unpaired segments (`ulength`), a window size, and a maximum base pair span computes the equilibrium probability of any segment not exceeding `ulength`. It is similar to vrna_pfl_fold_up() but uses a callback mechanism to return the unpaired probabilities.

    Read the details for vrna_probs_window() for details on the callback implementation!

    Note

    This function uses default model settings! For custom model settings, we refer to the function vrna_probs_window().

    Parameters:

      - sequence – The nucleic acid input sequence

      - ulength – The maximal length of an unpaired segment

      - window_size – The size of the sliding window

      - max_bp_span – The maximum distance along the backbone between two nucleotides that form a base pairs

      - cb – The callback function which collects the pair probability data for further processing

      - data – Some arbitrary data structure that is passed to the callback `cb`

    Returns:

      0 on failure, non-zero on success

  Defines

  VRNA_EXT_LOOP

    Exterior loop.

        #include <ViennaRNA/partfunc/local.h>

  VRNA_HP_LOOP

    Hairpin loop.

        #include <ViennaRNA/partfunc/local.h>

  VRNA_INT_LOOP

    Internal loop.

        #include <ViennaRNA/partfunc/local.h>

  VRNA_MB_LOOP

    Multibranch loop.

        #include <ViennaRNA/partfunc/local.h>

  VRNA_ANY_LOOP

    Any loop.

        #include <ViennaRNA/partfunc/local.h>

  VRNA_PROBS_WINDOW_BPP

    Trigger base pairing probabilities.

        #include <ViennaRNA/partfunc/local.h>

    Passing this flag to vrna_probs_window() activates callback execution for base pairing probabilities. In turn, the corresponding callback receives this flag through the `type` argument whenever base pairing probabilities are provided.

    Detailed information for the algorithm to compute unpaired probabilities can be taken from Bernhart et al. [2005] .

    See also

    vrna_probs_window()

  VRNA_PROBS_WINDOW_UP

    Trigger unpaired probabilities.

        #include <ViennaRNA/partfunc/local.h>

    Passing this flag to vrna_probs_window() activates callback execution for unpaired probabilities. In turn, the corresponding callback receives this flag through the `type` argument whenever unpaired probabilities are provided.

    Detailed information for the algorithm to compute unpaired probabilities can be taken from Bernhart et al. [2011] .

    See also

    vrna_probs_window()

  VRNA_PROBS_WINDOW_STACKP

    Trigger base pair stack probabilities.

        #include <ViennaRNA/partfunc/local.h>

    Passing this flag to vrna_probs_window() activates callback execution for stacking probabilities. In turn, the corresponding callback receives this flag through the `type` argument whenever stack probabilities are provided.

    Bug:

      Currently, this flag is a placeholder doing nothing as the corresponding implementation for stack probability computation is missing.

    See also

    vrna_probs_window()

  VRNA_PROBS_WINDOW_UP_SPLIT

    Trigger detailed unpaired probabilities split up into different loop type contexts.

        #include <ViennaRNA/partfunc/local.h>

    Passing this flag to vrna_probs_window() activates callback execution for unpaired probabilities. In contrast to VRNA_PROBS_WINDOW_UP this flag requests unpaired probabilities to be split up into different loop type contexts. In turn, the corresponding callback receives the VRNA_PROBS_WINDOW_UP flag OR-ed together with the corresponding loop type, i.e.:

    - VRNA_EXT_LOOP - Exterior loop.

    - VRNA_HP_LOOP - Hairpin loop.

    - VRNA_INT_LOOP - Internal loop.

    - VRNA_MB_LOOP - Multibranch loop.

    - VRNA_ANY_LOOP - Any loop.

    See also

    vrna_probs_window(), VRNA_PROBS_WINDOW_UP

  VRNA_PROBS_WINDOW_PF

    Trigger partition function.

        #include <ViennaRNA/partfunc/local.h>

    Passing this flag to vrna_probs_window() activates callback execution for partition function. In turn, the corresponding callback receives this flag through it’s `type` argument whenever partition function data is provided.

    See also

    vrna_probs_window()

    Note

    Instead of actually providing the partition function \(Z\), the callback is always provided with the corresponding enemble free energy \(\Delta G = - RT \ln Z\).

  Typedefs

  typedef void (*vrna_probs_window_f)(FLT_OR_DBL *pr, int pr_size, int i, int max, unsigned int type, void *data)

    Sliding window probability computation callback.

        #include <ViennaRNA/partfunc/local.h>

    Notes on Callback Functions:

      This function will be called for each probability data set in the sliding window probability computation implementation of vrna_probs_window(). The argument type specifies the type of probability that is passed to this function.

    Types:

    - VRNA_PROBS_WINDOW_BPP - Trigger base pairing probabilities.

    - VRNA_PROBS_WINDOW_UP - Trigger unpaired probabilities.

    - VRNA_PROBS_WINDOW_PF - Trigger partition function.

    The above types usually come exclusively. However, for unpaired probabilities, the VRNA_PROBS_WINDOW_UP flag is OR-ed together with one of the loop type contexts

    - VRNA_EXT_LOOP - Exterior loop.

    - VRNA_HP_LOOP - Hairpin loop.

    - VRNA_INT_LOOP - Internal loop.

    - VRNA_MB_LOOP - Multibranch loop.

    - VRNA_ANY_LOOP - Any loop.

    to indicate the particular type of data available through the `pr` pointer.

    See also

    vrna_probs_window(), vrna_pfl_fold_up_cb()

    Param pr:

      An array of probabilities

    Param pr_size:

      The length of the probability array

    Param i:

      The i-position (5’) of the probabilities

    Param max:

      The (theoretical) maximum length of the probability array

    Param type:

      The type of data that is provided

    Param data:

      Auxiliary data

  typedef void vrna_probs_window_callback(FLT_OR_DBL *pr, int pr_size, int i, int max, unsigned int type, void *data)

        #include <ViennaRNA/partfunc/local.h>