Functions
AMA_UnvMonoApprox.c File Reference
#include <AMA.h>

Functions

long int AMA_UnvMonoApprox (AMA_OPTIONS *options, long int n, double *x, double *z, double *epsilon, long int degree, AMA_SPLINE **spline)
 Monotonic Approximation of Univariate Data More...
 

Function Documentation

long int AMA_UnvMonoApprox ( AMA_OPTIONS options,
long int  n,
double *  x,
double *  z,
double *  epsilon,
long int  degree,
AMA_SPLINE **  spline 
)

Monotonic Approximation of Univariate Data

For a given set of data $(x_\ell,z_\ell)$ and approximation tolerances $\epsilon_\ell$, for $\ell=1,\ldots,N$, this function employs cnspla to compute the spline

\[ s(x) = \sum_{j=1}^{m}\alpha_jB_{d,j}(x|{\bf\Lambda}) \]

that minimizes

\[ F^{(2)}(s(x)) = \int_{x_1}^{x_N}\left( s^{(2)}(x) \right)^2 dx \]

subject to the approximation constraints

\[ z_\ell - \epsilon_\ell \le s(x_\ell) \le z_\ell + \epsilon_\ell, \]

for $\ell=1,\ldots,N$, and the local monotonicity constraints

\[ s'(x) \cases { \ge 0.0 {\rm \hspace{5pt}for\hspace{5pt}all\hspace{5pt}} x\in[x_\ell,x_{\ell+1}], & if $z_\ell + \epsilon_\ell < z_{\ell+1} - \epsilon_{\ell+1}$; \cr \le 0.0 {\rm \hspace{5pt}for\hspace{5pt}all\hspace{5pt}} x\in[x_\ell,x_{\ell+1}], & if $z_\ell - \epsilon_\ell > z_{\ell+1} + \epsilon_{\ell+1}$; \cr } \]

for $\ell=1,\ldots,N-1$. If for some $1\le \ell\le N-1$ the above conditions are not met, then the intervals $[z_\ell - \epsilon_\ell,z_\ell + \epsilon_\ell]$ and $[z_{\ell+1} - \epsilon_{\ell+1},z_{\ell+1} + \epsilon_{\ell+1}]$ intersect and the constraint $s'(x)=0$ can be imposed over the interval $[x_\ell,x_{\ell+1}]$. However, it is possible for the intervals $[z_q - \epsilon_q, z_q + \epsilon_q]$ and $[z_{q+1} - \epsilon_{q+1}, z_{q+1} + \epsilon_{q+1}]$ to intersect, for each $\ell\le q\le \ell+r$ and $r\ge 1$; without an intersection existing between all the intervals. In this case the equality constraint is inconsistent with the approximation constraints

\[ z_q - \epsilon_q \le s(x_q) \le z_q + \epsilon_q, \]

for $\ell\le q\le \ell+r+1$; and, therefore, can not be imposed over the interval $[x_l,x_{l+r+1}]$. Hence, instead of imposing an equality constraint this function minimizes $\vert\vert s'(x) \vert\vert_\infty$ over all intervals $[x_\ell,x_{\ell+1}]$ for which the intervals $[z_\ell - \epsilon_\ell,z_\ell + \epsilon_\ell]$ and $[z_{\ell+1} - \epsilon_{\ell+1},z_{\ell+1} + \epsilon_{\ell+1}]$ intersect.

In the above definition of $s(x)$ the $\alpha_j$, for $j=1,\ldots,m$, are the coefficients of the $m$ univariate B-splines $B_{d,j}(x|{\bf\Lambda})$ of degree $1\le d\le 5$ which are based on the knot vector ${\bf\Lambda}$. The knot vector ${\bf\Lambda}$ depends on the independent variable data, the degree and the continuity of the spline at the interior data points. This function computes a spline which satisfies either the full or reduced continuity condition at the interior data points, as well as, the approximation and local monotonicity constraints. The knot vector ${\bf\Lambda}$ is defined by AMA_LamdaMonoInterp().

The following table summarizes the continuity of $s(x_\ell)$, for $\ell=2,\ldots,N-1$, and the number of coefficients, $m$, for a spline that satisfies the full and reduced continuity conditions.

Degree Full Continuity $m$ Reduced Continuity $m$
Linear $s^{(p)}(x_\ell)$ is continuous for $p=0$ $N$ $s^{(p)}(x_\ell)$ is continuous for $p=0$ $N$
Quadratic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 1$ $2N$ $s^{(p)}(x_\ell)$ is continuous for $p=0$ $2N-1$
Cubic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 2$ $3N$ $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 1$ $2N$
Quartic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 3$ $4N$ $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 2$ $3N$
Quintic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 4$ $5N$ $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 3$ $4N$

This function performs the follow tasks:

  • Checks input parameters for validity, see AMA_UnvInputCheck().
  • Defines the spline $s(x)$ based on a knot vector defined by AMA_LamdaMonoInterp().
  • Defines CNSPLA_CONPNT constraints to represent the approximation constraints, see AMA_UnvConpnt().
  • Defines CNSPLA_CONREG constraints to represent the local monotonicity constraints, see AMA_UnvConreg().
  • Defines CNSPLA_PNLTRM condition to represent the function $F^{(2)}(s(x))$, see AMA_UnvPnltrm().
  • Invokes cnspla to compute a spline which minimizes $F^{(2)}(s(x))$ subject to the approximation and local monotonicity constraints.
  • Stores approximation into spline.
Note
By default the spline coefficients are initialized to zero but a different initial value for the spline coefficients can be set with AMA_OptionsSetCoefficients().
By default the monotonicity constraints are enabled but they can be disabled with AMA_OptionsSetMonotonicity().
By default the spline satisfies the full continutiy condition but the reduced continuity condition can be requested with AMA_OptionsSetContinuity().
Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_UnvMonoApprox().
n[in] The number of data points $N$. Must satisfy n $\ge 2$.
x[in] Array of size n containing the independent variable data $x_\ell$, for $\ell=1,\ldots,N$. Must be in strictly ascending order.
z[in] Array of size n containing the dependent variable data $z_\ell$, for $\ell=1,\ldots,N$.
epsilon[in] Array of size n containing the approximation tolerances $\epsilon_\ell$, for $\ell=1,\ldots,N$. Must satisfy $\epsilon_\ell\ge 0.0$ for all $\ell=1,\ldots,N$. If epsilon = NULL, then this function uses $\epsilon_\ell = 0.0$ for all $\ell=1,\ldots,N$.
degree[in] The degree $d$. Must satisfy $1\le$ degree $\le 5$.
spline[out] Pointer to AMA_SPLINE pointer containing the monotonic spline approximation. Must satisfy spline $\ne$ NULL.
Returns
Success/Error Code.

User Callable Function - Documented 101715