ILNumerics Ultimate VS

Interpolationinterp1 Method (InArraycomplex, InArrayDouble, InArrayDouble, Int32, InterpolationMethod)

ILNumerics Ultimate VS Documentation
ILNumerics - Technical Application Development
Interpolate data in one dimension, marking out-of-range values as NaN.

[ILNumerics Interpolation Toolbox]

Namespace:  ILNumerics.Toolboxes
Assembly:  ILNumerics.Toolboxes.Interpolation (in ILNumerics.Toolboxes.Interpolation.dll) Version: 5.5.0.0 (5.5.7503.3146)
Syntax

public static RetArray<complex> interp1(
	InArray<complex> V,
	InArray<double> X = null,
	InArray<double> Xn = null,
	int k = 1,
	InterpolationMethod method = InterpolationMethod.linear
)

Parameters

V
Type: ILNumericsInArraycomplex
Sample values, n-dimensional array of size [l1, l2, ... ln] with data values along the first dimension, or row vector of length l1.
X (Optional)
Type: ILNumericsInArrayDouble
[Optional] Positions for sample points in V; vector of length l1. Default: vec(0,l1-1).
Xn (Optional)
Type: ILNumericsInArrayDouble
[Optional] New query points; vector of length m. Default: (null) see parameter k.
k (Optional)
Type: SystemInt32
[Optional] Refinement factor. If Xn is null create new query points by splitting X k times into half. Default: 1 (splits once).
method (Optional)
Type: ILNumerics.ToolboxesInterpolationMethod
[Optional] Interpolation method. Default: linear.

Return Value

Type: RetArraycomplex
Returns interpolated values as array of size [m, l2,...,ln] at specified query points Xn, marking out-of range values as NaN.
Exceptions

ExceptionCondition
ArgumentNullExceptionIf input parameter V is NULL
ArgumentExceptionIf argument X is not ascending and distinct specified.
ArgumentExceptionIf argument method is set as global polynomial for more than 9 sample points X
ArgumentOutOfRangeExceptionIf arguments X and V have different size.
Remarks

interp1(InArraycomplex, Nullablecomplex, InArrayDouble, InArrayDouble, Int32, InterpolationMethod) performs one dimensional interpolation, i.e.: interpolation based on sample values V of one variable X at new query points Xn.

The array V contains the set of known sample values. If V is a vector a vector with the same orientation and length m is returned. If V is a n-dimensional array individual interpolations are performed for each column in V.

X defines the positions for the sample values along the columns in V as a vector of strictly monotonically increasing values. If X was specified as null a regular stepped range starting at 0 with step size 1 is assumed with the length of the working dimension in V.

The parameter Xn holds the vector of positions for the new query points. If Xn is ommitted query point positions are auto-created by splitting the ranges defined by X into half k times.

The following methods are supported:
  • nearest - Nearest neighbor interpolation returns the corresponding sample point from V which is closest to a new query point. This method needs little computing ressources.
  • previous - returns the sample point left from a new query point; corresponds to the floor() function. For query points outside of the specified domain the nearest available sample point is returned. At least 2 samples are required in each dimension. This function requires little resources and performs at about the same speed as nearest.
  • next - returns the sample point from V which is right from a new query point; corresponds to the ceil() function. If no 'next' sample is available (for extrapolating query points) the nearest sample is returned. At least 2 samples are required for V. This function needs little resources and performs with about the same speed as nearest and previous.
  • linear - Linear interpolation between adjacent sample points, produces continous function values but discontinuities in the first and higher derivatives. One will notice that the slopes of the interpolation result will change abruptly at the sample points. The algorithm uses insignificantly more ressources than nearest but significantly fewer ressources than polynomial, cubic and spline. At least two samples are required in V for linear interpolation.
  • parabolic, cubic and pp - Piecewise polynomial interpolation builds up a polynomial of order 2 or 3 respectively, based on the 3 or 4 points surrounding a query point. The interpolation result will be smooth in the function values and its first derivatives, but may introduce jumps in the second derivatives at the sample points. Due to its computational simplicity cubic interpolation is able to serve as a quick alternative to spline interpolation for large datasets with less strict smoothness requirements. At least 3 respectively 4 points are required in V for 'parabolic' and 'cubic' polynomials.
  • polynomial - performs global polynomial interpolation. The order of the polynomial function corresponds to the number of sample points V.Length. Due to the nature of higher order polynomials such 'global' interpolation is best suited for small sample sets with 3...7 sample values in V. For larger data, consider using one of the piecewise interpolations, like cubic or spline or the PolynomialInterpolatorSingle(InArraySingle, InArraySingle, NullableSingle, Int32) interpolation object and specify the order explicitely.
  • spline - cubic spline interpolation produces the smoothest results in terms of function values as well as its first and second derivatives. At least 3 sample points are required for V. The interpolation is the same as spline(InArraycomplex, Nullablecomplex, InArrayDouble, InArrayDouble, InArraycomplex, InArraycomplex), with not-a-knot boundary conditions at both end points. Consider using spline(InArraycomplex, Nullablecomplex, InArrayDouble, InArrayDouble, InArraycomplex, InArraycomplex) directly if more control of the boundary conditions is needed. This method brings the smoothest results in relation to its slightly higher computational demands. Despite its computational complexity, due to a carefully optimized implementation its speed is competitive to the other interpolation methods.

All interpolation methods in ILNumerics Interpolation Toolbox are well prepared to handle arbitrary array shapes for V, including empty arrays and row vectors. All, single and complex precision real and complex values (including NaN values) are supported. All functions are carefully parallelized for multicore systems and optimized for efficient, cache aware computations on large data.

interp1(InArraycomplex, Nullablecomplex, InArrayDouble, InArrayDouble, Int32, InterpolationMethod) is able to interpolate multiple sets of sample values at once. Individual interpolations are performed for each column of n-dimensional V.

This overload of interp1(InArraycomplex, InArrayDouble, InArrayDouble, Int32, InterpolationMethod) marks any resulting values with NaN which are laying outside of the domain of V, as specified by X. Use the overload interp1(InArraycomplex, Nullablecomplex, InArrayDouble, InArrayDouble, Int32, InterpolationMethod) in order to control the handling of those values.

Examples

//Define any 1-D function
Array<complex> X = linspace<complex>(-pi, pi, 10);
Array<complex> V = sin(x);

//define query points
Array<complex> Xn = linspace<complex>(-pi, pi, 30);

//Interpolation using all values
Array<complex> Vn = Interpolation.interp1(V, X, Xn, method: InterpolationMethod.spline, outOfRangeValues: complex.NaN);

//or interpolations using refinement factor
Array<complex> Vn = Interpolation.interp1(V, X, k:3, method: InterpolationMethod.spline, outOfRangeValues: complex.NaN);

//or just linear interpolation
Array<complex> Vn = Interpolation.interp1(V);

See Also

Reference