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)