# One-Dimensional Interpolation Functions

ILNumerics Interpolation Toolbox provides efficient functions for one-dimensional interpolation.

## Overview

One dimensional interpolation allows to compute new values from a set of known values in $R$. Values are computed based on a (hidden) function and the given data. The ILNumerics Interpolation Toolbox offers the following features and advantages for 1-dim interpolation:

- Established and well known single function interface: interp1(..).
- Based on ILNumerics Computing Engine for best performance, even on large data.
- Optional parameters for useful default values and easy implementation.
- Capable of handling all special arrays: NaN values, non-regular array shapes (empty) etc.
- Capable of handling complex values.
- High performance (auto parallelization on CPUs, internal optimizations)
- Out of range value detection.
- Optional extrapolation.

The function Interpolation.interp1 serves as a single entry point for all general one-dimensional interpolations. It performs all interpolation methods with common configurations. Only for spline interpolation a specialized function Interpolation.spline exists, which allows more specific configuration parameters. Spline functions are handled in a separate article.

## interp1() Function Prototypes

The interp1() function provides two overloads for each of the supported floating point element types (double, float, ILNumerics.complex, and ILNumerics.fcomplex). In the following all examples deal with the overloads for System.Double only:

For extensive parameter documentation consult the class reference for interp1.## Interpolation Methods

All available interpolation methods are listed in the enum type InterpolationMethod:

- InterpolationMethod.linear(default) - Linear interpolation. The interpolated value at a query point is based on linear interpolation of the values at adjacent grid points(requires at least 2 points). This method gives continous results but produces discontinous first derivative. Basically, it connects the values in V with straight lines. For its computational simplicity (and for compatibility reasons) this method is configured as the default method.
- InterpolationMethod.nearest - nearest neighbor interpolation. The resulting value at a query point equals the corresponding sample value from V which is
*closest*to the new query point. - InterpolationMethod.next - like nearest neighbor interpolation, but the interpolated value equals the value at the corresponding sample point from V which is
*right*from a new query point. - InterpolationMethod.previous - like 'next' but the resulting value equals the corresponding sample value in V which is
*left*from the new point. - InterpolationMethod.cubic - piecewise (local) cubic interpolation. The resulting value at a new query point is computed from a local cubic function, created from four neighboring grid points surrounding the query point (requires at least 4 points).
- InterpolationMethod.spline - spline interpolation. The interpolated value at a query point is based on a piecewise cubic interpolation of the values at neighboring grid points as well as additional smoothness conditions for 1st, 2nd, and 3rd derivatives (requires at least 4 points). This method is recommended for most situations, where a smooth result is required.
- InterpolationMethod.pp -
*piecewise*(local) polynomial interpolation. The interpolated value at a query point is based on piecewise polynomial functions. The minimal number of required values in V depends on the order of the polynomial function. This parameter is used in conjunction with ILPolynomialInterpolator only. - InterpolationMethod.polynomial - performs a
*global*polynomial interpolation.The interpolated value at a query point is based on piecewise polynomial functions. The minimal number of required values in V depends on the order of the polynomial function. This parameter is used in conjunction with ILPolynomialInterpolator only.

## Using interp1() Function for 1-dimensional Interpolation

The following examples demonstrate how Interpolation.interp1() is utilized, how its parameters are configured.

### Specifying Known Values

**Example**: Utlizing Interpolation.interp1() to create interpolated values from a simple set of measurement data.

Note, that only the array of measured values was given to the interp1() method. All optional parameters are auto-configured. This leads to the asumption of equally spaced measurement points, and the creation of 1 additional query point in the center between two given points of V. If no interpolation method is specified, linear interpolation is assumed.

The above call, therefore, leads to the same result as the following call, having all parameters explicitly defined:

Commonly, the interpolation is performed along the first dimension in V. However, if V is a vector, its orientation is not important but is retained for the result (shape preserving).

**Example**: Compute spline interpolated values of a sequence of $d = 10$ values $v = f(x) = sin(x)$, where $x \in {-1...1}$, defined as *row vector*. The result is again a row vector. Its number of elements is $dn = d * 2 - 1 = 19$:

Here, values for X are explicitely defined. Note, that X must be a vector with *strictly monotonically increasing *values of length V.S[wd], where wd corresponds to the working dimension in V. NaN values are not accepted for X.

The configuration of different *interpolation methods *is done by providing the method to use to the corresponding method parameter.

**Example**: Combining different interpolation methods and plotting the result.

### Specifying new Query Points

In the above examples, the new points for interpolation are determined automatically: If the parameter Xn is not provided positions for new query points are acquired by subdividing the bins of X. Basically, a new query point is placed in the center between two adjacent values of V. The number of such recursive subdivisions is controlled by the parameter k. A value of $k = 1$ leads to 1 new query point being inserted into each bin of V. For $k = 2$, 3 points are inserted, for $k = 3$: 5 points, a.s.f..

However, in general Xn determines the specific positions for new query points:

In difference to the positions defined in X, elements in Xn are not required to follow any order.

### Handling out-of-Range Values

Any elements in Xn which are smaller than X[0] or larger than X[end] are considered as 'out-of-range' of the domain of V and will get NaN values assigned to. A second overload of interp1() exists which allows the definition of an additional parameter outOfRangeValues. It is used to set the values which will be assigned to these query points laying outside of the domain of V. By setting this parameter to null, extrapolated values will be computed, otherwise the specific value will be assigned.

**Example**: Extrapolation using InterpolationMethod.cubic and outOfRangevalues = null:

## Performing Multiple Interpolations in Parallel

Interpolation.interp1() - as all interpolation functions in ILNumerics Interpolation Toolbox - is able to perform multiple similar interpolations at once, in parallel, utilizing multiple cores from your CPU very efficiently. This option brings best profit for gridded data interpolation and in all situations, where an ensemble of individual measurement data exist for one measurement setup.

**Example: **Ensemble interpolation of 10 measurements, with 5 measured values each.

### Shape of the Interpolation Result

When multiple value sets for interpolation are provided in V each the individual set is expected along the columns of V. Commonly, V will be a matrix. However, this is not obligatory and any dimensionality is allowed for V. Regardless of the state of its higher dimensions interpolation will still be performed along the columns of V. In the consequence, the shape of the interpolation result will preserve the original shape of V, replacing the columns with the result of individual interpolations.

**Example:** Interpolate columns of 3 dimensional data array.

## Numeric Type Support, Special Values

Following numerics element types are supported for V: System.Double, System.Single, ILNumerics.complex, ILNumerics.fcomplex. Note, that X and Xn are real values of corresponding precision. If V and/or Xn contain NaN values corresponding output elements will be NaN.