Data Handling and Manipulation — ViennaRNA Package

# Data Handling and Manipulation

It is not unusual that data needs to be tranformed before being used in any method or algorithm (pre-processing) or after it has been generated (post-processing). Here, we provide a generic implementation to transform an array of data into another array of data of the same size. Our implementation utilizes a callback mechanism that is responsible to transform any source value to a specific target value.

We already provide a handful of useful transformation functions through our Mathematical Functions API, e.g. linear functions, logarithms, logistic functions, but also bining and kernel density estimation (KDE). However, our choice to implement callback mechanism based transformation function(s) allows the users to implement any transformation function themselfs. This enables a wide range of possible adaptations of other methods throughout the ViennaRNA library that are build on top of the transformation functions.

Below are all API symbols for the data transform implementation.

## Data Transform API

  Defines

  VRNA_TRANSFORM_ENFORCE_DOMAIN_SOURCE

    Options flag for transforming linear data to enforce source domain limits.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  VRNA_TRANSFORM_ENFORCE_DOMAIN_TARGET

    Options flag for transforming linear data to enforce target domain limits.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  VRNA_TRANSFORM_ENFORCE_DOMAINS

    Options flag for transforming linear data to enforce source and target domain limits.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  VRNA_TRANSFORM_MAP_SOURCE_LOW

    Options flag for transforming linear data to map source values below the domain limit to the lower domain limit.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  VRNA_TRANSFORM_MAP_SOURCE_HIGH

    Options flag for transforming linear data to map source values above the domain limit to the upper domain limit.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  VRNA_TRANSFORM_MAP_SOURCE

    Options flag for transforming linear data to map source values below and above the domain limits to the domain limits.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  VRNA_TRANSFORM_MAP_TARGET_LOW

    Options flag for transforming linear data to map target values below the domain limit to the lower domain limit.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  VRNA_TRANSFORM_MAP_TARGET_HIGH

    Options flag for transforming linear data to map target values above the domain limit to the upper domain limit.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  VRNA_TRANSFORM_MAP_TARGET

    Options flag for transforming linear data to map target values below and above the domain limits to the domain limits.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  VRNA_TRANSFORM_MAP

    Options flag for transforming linear data to map source and target values below and above the domain limits to the respective domain limits.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  VRNA_TRANSFORM_DEFAULT

    Options flag for transforming linear data that indicates default settings.

        #include <ViennaRNA/data/transform.h>

    See also

    vrna_data_lin_transform()

  Functions

  double *vrna_data_lin_transform(const double *data, size_t data_size, vrna_math_fun_dbl_f transform_cb, vrna_math_fun_dbl_opt_t transform_opt, double domain[4], double oob_value, unsigned int options)

    Transform an array of linear data.

        #include <ViennaRNA/data/transform.h>

    This function transforms an array of linear data (`source`) into another array of linear data of the same size (`target`). For that purpose, it utilizes a callback mechanism that transforms each single value.

    During data transform, the callback function (`transform_cb`) will be executed for each value of the linear data (`data`) and is responsible to actually transform the data value. The `transform_opt` parameter will be simply passed-through to the callback function as second argument. The callback function has to return the transformed value.

    This transformation function may enforce source and target domain limits if the corresponding flag (VRNA_TRANSFORM_ENFORCE_DOMAINS) is provided to the `options` argument. This means that one has complete control over the accepted values of the source and target domains. The limits can be provided to this function through the `domain` argument. Here, the order of the limits follows:

    \[ x_\text{min}, x_\text{max}, y_\text{min}, y_\text{max}. \]

    If `NULL` is passed instead of an actual domain array, domain enforcement is deactivated and any value will pass. In case a domain enforcing is active and a source or target value doesn’t meet the respective limits, the function assigns it the out-of-bounds value `oob_value`. This behavior can be changed to a mapping of out-of-bounds values to the respetive domain limits. For that purpose, the `options` argument requires the flag VRNA_TRANSFORM_MAP.

    See also

    vrna_math_fun_dbl_f, vrna_math_fun_dbl_opt_t, VRNA_TRANSFORM_DEFAULT, VRNA_TRANSFORM_ENFORCE_DOMAINS, VRNA_TRANSFORM_ENFORCE_DOMAIN_SOURCE, VRNA_TRANSFORM_ENFORCE_DOMAIN_TARGET, VRNA_TRANSFORM_MAP, VRNA_TRANSFORM_MAP_SOURCE, VRNA_TRANSFORM_MAP_TARGET, VRNA_TRANSFORM_MAP_SOURCE_LOW, VRNA_TRANSFORM_MAP_SOURCE_HIGH, VRNA_TRANSFORM_MAP_TARGET_LOW, VRNA_TRANSFORM_MAP_TARGET_HIGH, vrna_math_fun_dbl_bin_opt(), vrna_math_fun_dbl_linear_opt(), vrna_math_fun_dbl_log_opt(), vrna_math_fun_dbl_logistic_opt(), vrna_math_fun_dbl_gaussian_opt(), vrna_math_fun_dbl_kde_opt()

    Note

    Individual control for mapping out-of-bounds values to the four domain limits, i.e. low and high values of source and target can be gained by providing the `options` argument the VRNA_TRANSFORM_MAP_SOURCE_LOW, VRNA_TRANSFORM_MAP_SOURCE_HIGH, VRNA_TRANSFORM_MAP_TARGET_LOW, and VRNA_TRANSFORM_MAP_TARGET_HIGH flags.

    Note

    When `data` is `NULL` or `data_size` equals `0`, the function returns `NULL`. Moreover, the function simply provides a copy of the linear data if the transformation callback `transform_cb` is not provided, i.e. if it is `NULL`. In this case, domain limits will still be enforced if the corresponding options are set.

    Parameters:

      - data – A pointer to an array of linear data

      - data_size – The size of the array `data` is pointing to

      - transform_cb – The data transformation callback (maybe `NULL`)

      - transform_opt – The options that need to be passed through to the transformation callback `transform_cb` (maybe `NULL`)

      - domain – The domain limits (maybe `NULL`)

      - oob_value – Out-of-bound value

      - options – Additional options that change the behavior of the transformation function

    Returns:

      A pointer to an array of transformed linear data (or `NULL` on any error)