Mathematical Functions

Below you’ll find the API description for our mathematical functions.

Scalar Mathematical Functions API

Defines

VRNA_MATH_FUN_BIN_OPTION_PROJECT

Options flag for linear data binning to activate data projection (mapping) instead of actual binning.

#include <ViennaRNA/math/functions.h>

VRNA_MATH_FUN_BIN_OPTION_MAP_OUTOF_UPPERBOUND

Options flag for linear data binning to indicate that values out-of-upper-bound are to be mapped to the respective domain limit.

#include <ViennaRNA/math/functions.h>

VRNA_MATH_FUN_BIN_OPTION_MAP_OUTOF_LOWERBOUND

Options flag for linear data binning to indicate that values out-of-lower-bound are to be mapped to the respective domain limit.

#include <ViennaRNA/math/functions.h>

VRNA_MATH_FUN_BIN_OPTION_DEFAULT

Options flag for linear data binning to indicate default settings.

#include <ViennaRNA/math/functions.h>

VRNA_MATH_FUN_LINEAR_OPTION_LOG

Options flag for transforming linear data using a linear function that enables log-transform of the source value.

#include <ViennaRNA/math/functions.h>

VRNA_MATH_FUN_LINEAR_OPTION_DEFAULT

Options flag for transforming linear data using linear function that indicates default settings.

#include <ViennaRNA/math/functions.h>

VRNA_MATH_FUN_LOG_OPTION_NONDEFAULT_BASE

Options flag for transforming linear data using log transform to use a non-default base.

#include <ViennaRNA/math/functions.h>

VRNA_MATH_FUN_LOG_OPTION_DEFAULT

Options flag for transforming linear data using log transform that indicates default settings.

#include <ViennaRNA/math/functions.h>

VRNA_MATH_FUN_LOGISTIC_OPTION_DEFAULT

Options flag for transforming linear data using logistic function that indicates default settings.

#include <ViennaRNA/math/functions.h>

VRNA_MATH_FUN_KDE_OPTION_DEFAULT

Options flag for transforming linear data using a kernel density estimate (KDE) that indicates default settings.

#include <ViennaRNA/math/functions.h>

VRNA_MATH_FUN_GAUSSIAN_OPTION_DEFAULT

Options flag for transforming linear data using a Gaussian function that indicates default settings.

#include <ViennaRNA/math/functions.h>

Typedefs

typedef void *vrna_math_fun_dbl_opt_t

Option data structure type for mathematical functions.

#include <ViennaRNA/math/functions.h>

typedef vrna_auxdata_free_f vrna_math_fun_dbl_opt_free_f

Callback function to release any memory occupied by the mathematical function option vrna_math_fun_dbl_opt_t.

#include <ViennaRNA/math/functions.h>

typedef double (*vrna_math_fun_dbl_f)(double value, vrna_math_fun_dbl_opt_t options)

Callback function prototype for scalar mathematical functions of the form \( y = f(x) \).

#include <ViennaRNA/math/functions.h>

This is the prototype for callback functions used for scalar mathematical functions. Its main purpose is to encapsulate the options (arguments, such as constansts, etc.) for the mathematical function and can therefore be used in a more generalized way wherever different mathematical functions may be applied in the same manner. Functions of this type have to be provided two parameters: value which is the value \( x \) that is about to be evaluated options, which is a pointer to a data structure that holds any means required to ensure that the callback can evaluate the provide data. The callback function then returns the transformed value \( y \).

Notes on Callback Functions:: This callback handles mathematical functions working on scalar double values.

Param value:: The value \( x \) that is to be evaluated by the function \( f(x) \)
Param options:: A pointer to a data structure specific for the mathematical function
Return:: The evaluated value \( y \)

Functions

double vrna_math_fun_dbl_bin(double value, double (*thresholds)[2], size_t thresholds_num, double oolb_value, double ooub_value, unsigned int options)

Bin a scalar input value or project it from one domain into another.

#include <ViennaRNA/math/functions.h>

This function can be used to map continuous data from one domain (source) into discrete or continuous data of another domain (target). User-defined domain boundaries are provided by the thresholds argument, which boils down to a list of pairs of values, where the first value is the boundary in the source domain. The second value is the corresponding boundary of the target domain. The first and last pair of domain boundaries denote the lower and the upper domain limits, respectively. Any value outside of these limits can either be discarded by assigning them a special out-of-bounds value (oolb_value, ooub_value), or they can be mapped directly to the domain limits. Control over this mapping is available through the options argument by using the binary flags VRNA_MATH_FUN_BIN_OPTION_MAP_OUTOF_UPPERBOUND and VRNA_MATH_FUN_BIN_OPTION_MAP_OUTOF_LOWERBOUND.

By default, the transformation maps any data within a source interval as specified by two consecutive entries in the thresholds argument to the exact value of the second target boundary. This process is also called binning. Alternatively, this implementation also allows for a continuous mapping (projection) of the source intervals into the target intervals. To activate this behavior, the VRNA_MATH_FUN_BIN_OPTION_PROJECT flag must be provided to the options argument.

Parameters:

value – The input value
thresholds – A pointer to an array of data pairs holding the source and target domain boundaries
thresholds_num – The number of domain boundary pairs available in thresholds
oolb_value – Out-of-lower-bound value
ooub_value – Out-of-upper-bound value
options – Additional options that change the behavior of this function

Returns:

The projection of the input value into the target domain

vrna_math_fun_dbl_f vrna_math_fun_dbl_bin_opt(double (*thresholds)[2], unsigned int thresholds_num, double oolb_value, double ooub_value, unsigned int options, vrna_math_fun_dbl_opt_t *fun_options_p, vrna_math_fun_dbl_opt_free_f *fun_options_free)

Retrieve a function pointer that performs (discrete) binning and more.

#include <ViennaRNA/math/functions.h>

This function yields a linear data transform callback and the associated transform options data structure suitable for usage in vrna_data_lin_transform(). The transformation this callback performs can be described as (discrete) binning or data bucketing and essentially encapsulates the vrna_math_fun_dbl_bin() function.

The fun_options_p and fun_options_free pointers are used as additional output to obtain the addresses of the transformation option data structure that has to be provided to the vrna_data_lin_transform() function and a function pointer to release the memory of the option data structure once it is not required anymore.

Parameters:

thresholds – A pointer to an array of data pairs holding the source and target domain boundaries
thresholds_num – The number of domain boundary pairs available in thresholds
oolb_value – Out-of-lower-bound value
ooub_value – Out-of-upper-bound value
options – Additional options that change the behavior of the callback function
fun_options_p – A pointer to store the address of the options data structure
fun_options_free – A pointer to store the address of the free function that releases the memory of the options data structure

Returns:

A callback function that performs (discrete) data binning

double vrna_math_fun_dbl_linear(double x, double slope, double intercept, unsigned int options)

Transform a scalar input value through a linear function.

#include <ViennaRNA/math/functions.h>

This function can be used to transform an input value (parameter x) into an output value by applying a linear function of the form

\[ y = a + b \cdot f(x) \]

where \( x \) is the input value (source), \( a \) and \( b \) are intercept and slope, and \( y \) is the output value (target). By default, the function \( f(x) = x \) is the identity function. However, the callback can be instructed to apply a log-transform, \( f(x) = log x \), instead. Control over the behavior of \( f(x) \) can be gained by providing a corresponding option flag to the options argument, e.g. VRNA_MATH_FUN_LINEAR_OPTION_LOG.

Parameters:

x – The input value
slope – The slope of the linear function
intercept – The intercept of the linear function
options – Additional options that change the behavior of the callback function

Returns:

The transformed output value \( y \)

vrna_math_fun_dbl_f vrna_math_fun_dbl_linear_opt(double slope, double intercept, unsigned int options, vrna_math_fun_dbl_opt_t *fun_options_p, vrna_math_fun_dbl_opt_free_f *fun_options_free)

Retrieve a function pointer that applies a linear function.

#include <ViennaRNA/math/functions.h>

This function yields a linear data transform callback and the associated transform options data structure suitable for usage in vrna_data_lin_transform(). The callback applies a linear function \( y = a + b \cdot f(x) \) and essentially encapsulates the vrna_math_fun_dbl_linear() function.

The fun_options_p and fun_options_free pointers are used as additional output to obtain the addresses of the transformation option data structure that has to be provided to the vrna_data_lin_transform() function and a function pointer to release the memory of the option data structure once it is not required anymore.

Parameters:

slope – The slope of the linear function
intercept – The intercept of the linear function
options – Additional options that change the behavior of the callback function
fun_options_p – A pointer to store the address of the options data structure
fun_options_free – A pointer to store the address of the free function that releases the memory of the options data structure

Returns:

A callback function that performs transformation through a linear model

double vrna_math_fun_dbl_log(double x, double base, double oob_value, unsigned int options)

Transform a scalar input value through a logarithmic function.

#include <ViennaRNA/math/functions.h>

This function transforms a scalar input value by computing the logarithm function

\[ y = \log_b x \]

where \( x \) is the input value (source), \( b \) is the base, and \( y \) is the output value (target). By default, the natural logarithm is used, i.e. \( b = \mathrm{e} \). The base argument in combination with the VRNA_MATH_FUN_LOG_OPTION_NONDEFAULT_BASE flag supplied to the options argument can be used to change the base to any other number.

The function returns the user-specified out-of-bounds value oob_value if \( x \le 0 \).

Parameters:

x – The input value
base – The base \( b \) of the logarithm (only used if VRNA_MATH_FUN_LOG_OPTION_NONDEFAULT_BASE is passed to options
oob_value – Out-of-bound value
options – Additional options that change the behavior of the callback function

Returns:

The transformed target value \( y \)

vrna_math_fun_dbl_f vrna_math_fun_dbl_log_opt(double value_shift, double base, double oob_value, unsigned int options, vrna_math_fun_dbl_opt_t *fun_options_p, vrna_math_fun_dbl_opt_free_f *fun_options_free)

Retrieve a function pointer a logarithmic function.

#include <ViennaRNA/math/functions.h>

This function yields a linear data transform callback and the associated transform options data structure suitable for usage in vrna_data_lin_transform(). The callback applies a logarithmic function \( y = \log_b (x + c) \) and essentially encapsulates the vrna_math_fun_dbl_log() function. Note, that here, the value_shift argument corresponds to \( c \) in the above formula and in most cases should be 0. The callback then returns the out-of-bounds value oob_value if \( x + c \le 0 \).

The fun_options_p and fun_options_free pointers are used as additional output to obtain the addresses of the transformation option data structure that has to be provided to the vrna_data_lin_transform() function and a function pointer to release the memory of the option data structure once it is not required anymore.

Parameters:

value_shift – The shift value \( c \)
base – The base \( b \) of the logarithm (only used if VRNA_MATH_FUN_LOG_OPTION_NONDEFAULT_BASE is passed to options
oob_value – Out-of-bound value
options – Additional options that change the behavior of the callback function
fun_options_p – A pointer to store the address of the options data structure
fun_options_free – A pointer to store the address of the free function that releases the memory of the options data structure

Returns:

A callback function that performs transformation through a linear model

double vrna_math_fun_dbl_logistic(double x, double mid_point, double supremum, double growth_rate, unsigned int options)

Transform a scalar input value through a logistic function.

#include <ViennaRNA/math/functions.h>

This function transforms a scalar input value by applying a logistic function of the form

\[ y = \frac{L}{1 + e^{-k \cdot (x - x_0)}} \]

where \( x \) is the input value (source), \( x_0 \) is the mid point (mid_point) of the function, \( k \) is the logistic growth rate (growth_rate), and \( L \) is the supremum (or carrying capacity) of the function (supremum). The standard logistic function is defined as \( L = 1 \), \( k = 1 \). and \( x_0 = 0 \), i.e.

\[ y = \frac{1}{1 + e^{-x}} \]

Parameters:

x – The input value
mid_point – The midpoint of the function
supremum – The supremum of the function
growth_rate – The growth rate of the function
options – Additional options that change the behavior of the callback function

Returns:

The transformed target value \( y \)

vrna_math_fun_dbl_f vrna_math_fun_dbl_logistic_opt(double mid_point, double supremum, double growth_rate, unsigned int options, vrna_math_fun_dbl_opt_t *fun_options_p, vrna_math_fun_dbl_opt_free_f *fun_options_free)

Retrieve a function pointer that applies a logistic function.

#include <ViennaRNA/math/functions.h>

This function yields a linear data transform callback and the associated transform options data structure suitable for usage in vrna_data_lin_transform(). The callback applies a logistic function of the form

\[ y = \frac{L}{1 + e^{-k \cdot (x - x_0)}} \]

and essentially encapsulates the vrna_math_fun_dbl_logistic() function.

The fun_options_p and fun_options_free pointers are used as additional output to obtain the addresses of the transformation option data structure that has to be provided to the vrna_data_lin_transform() function and a function pointer to release the memory of the option data structure once it is not required anymore.

Parameters:

mid_point – The midpoint of the function
supremum – The supremum of the function
growth_rate – The growth rate of the function
options – Additional options that change the behavior of the callback function
fun_options_p – A pointer to store the address of the options data structure
fun_options_free – A pointer to store the address of the free function that releases the memory of the options data structure

Returns:

A callback function that performs transformation through a logistic function

double vrna_math_fun_dbl_kde(double x, double *samples, size_t num_samples, vrna_math_fun_dbl_f kernel, vrna_math_fun_dbl_opt_t kernel_data, double bandwidth, unsigned int options)

Estimate the probability density for a scalar input value through kernel density estimation (KDE).

#include <ViennaRNA/math/functions.h>

This function estimates the probability density function of a random input variable given a set of samples and a smoothing kernel. The estiamte of the probability density for a random variable \( x \) is then of the form

\[ y = \hat{f}_h(x) = \frac{1}{n \cdot h} \sum_{i = 1}^{n} K \big( \frac{x - x_i}{h} \big) \]

with a set of \( n > 0 \) samples \( \{ x_1, x_2, \ldots, x_n \} \) (samples), \( K \) (kernel) as a non-negative kernel function, and \( h > 0 \) is the bandwidth (bandwidth).

Note

If no kernel is provided, i.e. NULL is passed to kernel, the KDE uses a standard Gaussian kernel by providing vrna_math_fun_dbl_gaussian() with \( a = \frac{1}{\sqrt{2 \pi}}, b = 0, c = 1 \). In this case, the bandwidth (bandwidth) will be automatically replaced by a rule-of-thumb bandwidth estimator \( h = ( \frac{4}{3n} )^{\frac{1}{5}} \)

Parameters:

x – The input value
samples – The samples of the distribution to estimate \( \{ x_1, x_2, \ldots, x_n \} \)
num_samples – The number of samples ( \( n \)) provided by pointer samples
kernel – The kernel function \( K \) (maybe NULL)
kernel_data – The data that should be passed-through to the kernel function (maybe NULL)
bandwidth – The bandwidth \( h \)
options – Additional options that change the behavior of the callback function

Returns:

The estimated probability density \( \hat{f}_h(x) \)

vrna_math_fun_dbl_f vrna_math_fun_dbl_kde_opt(double *samples, size_t num_samples, vrna_math_fun_dbl_f kernel, vrna_math_fun_dbl_opt_t kernel_data, vrna_math_fun_dbl_opt_free_f kernel_data_free, double bandwidth, unsigned int options, vrna_math_fun_dbl_opt_t *fun_options_p, vrna_math_fun_dbl_opt_free_f *fun_options_free)

Retrieve a callback function that applies a kernel density estimation (KDE).

#include <ViennaRNA/math/functions.h>

This function yields a linear data transform callback and the associated transform options data structure suitable for usage in vrna_data_lin_transform(). The callback applies a kernel density estimation (KDE) and essentially encapsulates the vrna_math_fun_dbl_kde() function.

The fun_options_p and fun_options_free pointers are used as additional output to obtain the addresses of the transformation option data structure that has to be provided to the vrna_data_lin_transform() function and a function pointer to release the memory of the option data structure once it is not required anymore.

Note

Whenever the fun_options_free callback will be called, this function also releases the memory occupied by kernel_data through the kernel_data_free function if it is provided, i.e. not NULL.

Parameters:

samples – The samples of the distribution to estimate \( \{ x_1, x_2, \ldots, x_n \} \)
num_samples – The number of samples ( \( n \)) provided by pointer samples
kernel – The kernel function \( K \) (maybe NULL)
kernel_data – The data that should be passed-through to the kernel function (maybe NULL)
kernel_data_free – A function to free the memory occupied by the data for the kernel function (maybe NULL)
bandwidth – The bandwidth \( h \)
options – Additional options that change the behavior of the callback function
fun_options_p – A pointer to store the address of the options data structure
fun_options_free – A pointer to store the address of the free function that releases the memory of the options data structure

Returns:

A callback function that performs transformation through kernel density estimation

double vrna_math_fun_dbl_gaussian(double x, double a, double b, double c)

Evaluate a Gaussian function for a scalar input value.

#include <ViennaRNA/math/functions.h>

This function applies a Gaussian function of the form

\[ y = f(x) = a \cdot \exp(- \frac{(x - b)^2}{2 c^2}) \]

with arbitrary constants \( a, b \) and non-zero \( c \) to a scalar input value \( x \).

See also

vrna_math_fun_dbl_gaussian_opt()

Parameters:

x – The input value \( x \)
a – The arbitrary constant \( a \)
b – The arbitrary constant \( b \)
c – The arbitrary non-zero constant \( c \)

Returns:

The evaluation for the Gaussian function \( y = f(x) \)

vrna_math_fun_dbl_f vrna_math_fun_dbl_gaussian_opt(double a, double b, double c, unsigned int options, vrna_math_fun_dbl_opt_t *fun_options_p, vrna_math_fun_dbl_opt_free_f *fun_options_free)

Retrieve a function pointer that applies Gaussian function.

#include <ViennaRNA/math/functions.h>

This function yields a linear data transform callback and the associated transform options data structure suitable for usage in vrna_data_lin_transform(). The callback applies a Gaussian function of the form

\[ y = a \cdot \exp(- \frac{(x - b)^2}{2 c^2}) \]

with arbitrary constants \( a, b \) and non-zero \( c \) and \( x \) being the input value (source).

The fun_options_p and fun_options_free pointers are used as additional output to obtain the addresses of the transformation option data structure that has to be provided to the vrna_data_lin_transform() function and a function pointer to release the memory of the option data structure once it is not required anymore.

Parameters:

a – The arbitrary constant \( a \)
b – The arbitrary constant \( b \)
c – The arbitrary non-zero constant \( c \)
options – Additional options that change the behavior of the callback function
fun_options_p – A pointer to store the address of the options data structure
fun_options_free – A pointer to store the address of the free function that releases the memory of the options data structure

Returns:

A callback function that performs transformation through a Gaussian function

vrna_math_fun_dbl_f vrna_math_fun_dbl_chain(vrna_math_fun_dbl_f first_f, vrna_math_fun_dbl_opt_t first_f_opt, vrna_math_fun_dbl_opt_free_f first_f_opt_free, vrna_math_fun_dbl_opt_t *fun_options_p, vrna_math_fun_dbl_opt_free_f *fun_options_free)

#include <ViennaRNA/math/functions.h>

size_t vrna_math_fun_dbl_chain_append(vrna_math_fun_dbl_opt_t chain_opt, vrna_math_fun_dbl_f f, vrna_math_fun_dbl_opt_t f_opt, vrna_math_fun_dbl_opt_free_f f_opt_free)

#include <ViennaRNA/math/functions.h>

size_t vrna_math_fun_dbl_chain_size(vrna_math_fun_dbl_opt_t chain)

#include <ViennaRNA/math/functions.h>

vrna_math_fun_dbl_f vrna_math_fun_dbl_chain_at(vrna_math_fun_dbl_opt_t chain, size_t pos, vrna_math_fun_dbl_opt_t *fun_options_p)

#include <ViennaRNA/math/functions.h>