
Calling Sequence


f := NearestNeighborInterpolation(xdata, ydata, options)
f := NearestNeighborInterpolation(xydata, options)
f := LowestNeighborInterpolation(xdata, ydata, options)
f := LowestNeighborInterpolation(xydata, options)
f := HighestNeighborInterpolation(xdata, ydata, options)
f := HighestNeighborInterpolation(xydata, options)
f := LinearInterpolation(xdata, ydata, options)
f := LinearInterpolation(xydata, options)
f := CubicInterpolation(xdata, ydata, options)
f := CubicInterpolation(xydata, options)
f := SplineInterpolation(xdata, ydata, options)
f := SplineInterpolation(xydata, options)
f(x1, x2, ..., xn, options)
f(xvalues, options)


Parameters


xdata



a list, Array, DataFrame, DataSeries, Vector, or Matrix containing the independent coordinate(s) of each of the data points, given in one of several possible forms

ydata



a list, Array, DataSeries, or Vector containing the dependent coordinate of each of the data points

xydata



alternate input; a list, Array, DataFrame, or Matrix containing both the dependent and independent coordinates of each of the data points

xvalues



a numeric value, list, Vector, or Array containing the independent coordinate(s) of one or more points whose dependent coordinate will be approximated using interpolation

x1, x2, ..., xn



numeric values; independent coordinate(s) of one point whose dependent coordinate will be approximated using interpolation

options



(optional) equation(s) of the form keyword = value, where keyword is one of method, degree, endpoints, knots, uniform, verify, extrapolate, or container.





Description


•

The NearestNeighborInterpolation, LowestNeighborInterpolation, HighestNeighborInterpolation, LinearInterpolation, CubicInterpolation, and SplineInterpolation commands take a finite set of distinct data points given by xdata and ydata (or xydata), and return an object. This object can interpolate to approximate the yvalues corresponding to the points given in xvalues, or in x1, x2, ..., xn. It considers an interpolant function $f$ such that $f\left(x\right)=y$ for all respective pairs$\left(x\,y\right)$ in xdata and ydata (or xydata). Such a function can be constructed using one of various methods; the commands differ in the method used.

•

The commands described in this help page use the ArrayInterpolation command from the CurveFitting package. If you know all xvalues at which you want to evaluate the interpolant beforehand, you may get slightly better performance calling that command directly. Conversely, the commands on this help page provide better performance if you want to iteratively evaluate the interpolant at various points one by one. Furthermore, to actually compute and return interpolants, functions such as CurveFitting[Spline] and CurveFitting[RationalInterpolation] can be used instead.

•

The list of independent coordinates of the data points, given in xdata, can be input in a number of different ways. xdata can be:

–

(preferred if $n=1$) a Vector, DataSeries, list, or onedimensional Array of strictly increasing xcoordinates. The data set will then have size ${a}_{1}$, where ${a}_{1}$ is the length of xdata.

–

(preferred if $1<n$) a list of $n$ Vectors, lists, or onedimensional Arrays, one for each dimension of the data. The $j$th Vector, list, or Array in the input must contain, in increasing order, all of the possible $j$th coordinates of the data points. In this case, the block of data points will be assumed to lie on an ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$ grid, where ${a}_{j}$ is the length of the $j$th Vector or Array in the input. The $p$th coordinate of the data point at index $\[{j}_{1},{j}_{2},\; ...,{j}_{n}\]$ (where $1\le {j}_{i}\le {a}_{i}$) will be equal to the ${a}_{p}$th element of the $p$th Array in the input.

–

an Array of size ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$ by $n$, giving the independent coordinate(s) of each of ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$ data points as an ordered $n$tuple. These coordinates must form a proper "grid" of values, and must be sorted in strictly increasing order along each dimension. More formally, $\mathrm{xdata}\[{j}_{1},{j}_{2},\; ...,{j}_{n},p\]\mathrm{xdata}\[{k}_{1},{k}_{2},\; ...,{k}_{n},p\]$ must be zero if ${j}_{p}={k}_{p}$, and must be positive if ${k}_{p}<{j}_{p}$.

–

a list of $n$ Arrays of size ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$, where the $j$th array contains the $j$th independent coordinate of each of the ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$ data points. The coordinates must form a proper "grid" of values, and must be sorted in strictly increasing order along each dimension. More formally, $\mathrm{op}\left(p\,\mathrm{xdata}\right)\[{j}_{1},{j}_{2},\; ...,{j}_{n}]\; \mathrm{op}\left(p\,\mathrm{xdata}\right)\[{k}_{1},{k}_{2},\; ...,{k}_{n}\]$ must be zero if ${j}_{p}={k}_{p}$, and must be positive if ${k}_{p}<{j}_{p}$.


The preferred methods minimize memory usage and execution time by avoiding unnecessary storage and verification of redundant data during the definition of f; there is no difference once f has been defined. In all cases, xdata must contain real values of type numeric.

•

The list of dependent coordinates of the data points, given in ydata, must be input as an Array (or a Matrix, Vector, or list for appropriate values of $n$) of size ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$, so that the value of $\mathrm{ydata}\[{j}_{1},{j}_{2},\; ...,{j}_{n}\]$ corresponds to the element in xdata of index $\[{j}_{1},{j}_{2},\; ...,{j}_{n}\]$. Values in ydata must be real numbers of type extended_numeric.

•

As an alternate form of input, a single structure xydata containing all coordinates of the data points can be entered. It can be formatted in one of the following ways:

–

an Array, DataFrame, or Matrix of size ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$ by ($n+1$), giving the independent and dependent coordinate(s) of each of ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$ data points as an ordered ($n+1$)tuple. The first n elements in each ($n+1$)tuple represent the independent coordinates of each point, and must adhere to the same restrictions as above (a proper "grid" must be formed, and the independent coordinates must be sorted in strictly increasing order along each dimension). The $n+1$st coordinate in each ($n+1$)tuple then represents the dependent coordinate of the respective data point.

–

a list of $n+1$ Arrays, Vectors, Matrices, or lists of size ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$, where the $j$th array contains the $j$th independent coordinate of each of the ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$ data points for $1\le j\le n$, and the $n+1$st Array contains the dependent coordinates of each point. As above, the independent coordinates must adhere to certain restrictions (a proper "grid" must be formed, and the independent coordinates must be sorted in strictly increasing order along each dimension).


For multidimensional data, these methods are not recommended, since space is wasted storing the full grid of independent coordinates instead of a list of all the possible coordinates in each dimension. In both cases, the coordinates must be real values of type numeric.

•

There are two ways to use the object f, created by these calling sequences:

–

You can evaluate f at a single point x1, x2, ..., xn, by supplying these values as arguments.

–

You can evaluate f at multiple points at once; how this works depends on whether $n=1$ or $1<n$:

•

For onedimensional data, a Vector, list, or onedimensional Array of numeric values can be input. The output will be returned in a format matching the format of the input.

•

For multidimensional data, an Array or Matrix of size ${u}_{1}$ by ${u}_{2}$ by ... by ${u}_{k}$ by $n$ of numeric values can be input. It must contain the $n$ coordinates of each of ${u}_{1}$ by ${u}_{2}$ by ... by ${u}_{k}$ values to interpolate at, with the value of $\mathrm{xvalues}\[{j}_{1},{j}_{2},\; ...,{j}_{k},p\]$ giving the $p$th coordinate of the respective point. The output will be returned in an array of size ${u}_{1}$ by ${u}_{2}$ by ... by ${u}_{k}$ containing the interpolated results.

•

Alternatively, a list of $n$ Vectors, lists, or onedimensional Arrays can be input. The $j$th Vector, list, or Array in the input will be assumed to contain all of the possible $j$th coordinates of the values to interpolate at. In this case, interpolation will be performed on an ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$ block of points, where ${a}_{j}$ is the length of the $j$th Vector or Array in the input. The output will then be returned in a Vector, Matrix, list, or Array of size ${a}_{1}$ by ${a}_{2}$ by ... by ${a}_{n}$.

•

If any of the data points in xvalues lie outside the rectangular bounding box specified by the input, then extrapolation will be performed to approximate their corresponding yvalues. The method by which extrapolation is performed can be controlled by using option extrapolate; see below.

•

This command has separate numeric methods for handling hardware and software floats. The decision about which routine to use can be controlled by setting the UseHardwareFloats environment variable. If UseHardwareFloats remains unset, then hardware floats are used if and only if $\mathrm{Digits}\le \mathrm{evalhf}\left(\mathrm{Digits}\right)$, in which case all software floats in the input will be converted to hardware floats. If UseHardwareFloats or Digits are modified in between defining f and using it, the accuracy and performance may be worse than if you set the desired setting at the start.

•

Only computations involving numeric floatingpoint data are supported by this routine. If the input does not contain floatingpoint data, an error will be thrown.

•

For optimal performance, all rtables in the input should be Fortran order with rectangular storage (the default). Otherwise, a conversion will take place. All rtables in the output will be Fortran order rtables with rectangular storage.

•

This function is part of the Interpolation package, so it can be used in the short form LinearInterpolation(..) etc. only after executing the command with(Interpolation). However, it can always be accessed through the long form of the command by using Interpolation[LinearInterpolation](..).



The Interpolating Functions


•

This section describes the way in which f interpolates the given data points for each of the different commands possibly used to define f. They correspond to different method options for the CurveFitting[ArrayInterpolation] command.

•

NearestNeighborInterpolation (corresponds to method = nearest): Perform nearest neighbor interpolation. Given a point $u$, $f\left(u\right)$ is defined to be $y$, where$\left(x\,y\right)$ is the data point such that the Euclidean distance $\Vert xu\Vert$ is minimized.

•

LowestNeighborInterpolation (corresponds to method = lowest): Perform lowest neighbor interpolation. Given a point $u$ in xvalues, $f\left(u\right)$ is defined to be $y$, where$\left(x\,y\right)$ is the data point such that $ux$ is nonnegative in all coordinates, but the Euclidean distance $\Vert xu\Vert$ is minimized.

•

HighestNeighborInterpolation (corresponds to method = highest): Perform highest neighbor interpolation. Given a point $u$ in xvalues, $f\left(u\right)$ is defined to be $y$, where$\left(x\,y\right)$ is the data point such that $xu$ is nonnegative in all coordinates, but the Euclidean distance $\Vert xu\Vert$ is minimized.

•

LinearInterpolation (corresponds to method = linear): Perform $n$dimensional linear interpolation (lerping). In the onedimensional case, $f$ is a piecewiselinear function passing through each data point$\left(x\,y\right)$ in the input. In the multidimensional case, $f$ is the tensor product of $n$ such piecewise linear functions, one for each dimension. $f\left(u\right)$ is computed by performing linear interpolation along the first dimension, then along the second dimension, and so on.

•

CubicInterpolation (corresponds to method = cubic): Perform piecewise cubic Hermite interpolation. In the onedimensional case, $f$ is a piecewisecubic function passing through each data point$\left(x\,y\right)$ in the input. In this case, $f\left(u\right)$ = ${f}_{i}\left(u\right)$ if $u$ lies in the interval $\left[{x}_{i}\,{x}_{i+1}\right]$, where each ${f}_{i}$ is a cubic polynomial such that ${f}_{i}\left({x}_{i}\right)={y}_{i}$ and ${f}_{i}\left({x}_{i+1}\right)={y}_{i+1}$ for all data points $\left({x}_{i}\,{y}_{i}\right)$ in the input (where $i$ ranges from $0$ to $k$). The coefficients of the functions ${f}_{i}$ are determined locally by assigning slopes ${s}_{i}$ to each data point ${x}_{i}$ and solving for the unique cubic function ${f}_{i}\left(x\right)$ determined by the additional constraints that ${f}_{i}\text{'}\left({x}_{i}\right)={s}_{i}$and${f}_{i}\text{'}\left({x}_{i+1}\right)={s}_{i+1}$. This forces $f$ to be continuously differentiable ($\mathrm{C1}$). The ${s}_{i}$ themselves are computed using Bessel's method: ${s}_{i}$ is the slope at ${x}_{i}$ of the parabola passing through ${x}_{i1},{y}_{i1}$, ${x}_{i},{y}_{i}$, and ${x}_{i+1},{y}_{i+1}$. In the multidimensional case, $f$ is the tensor product of $n$ such cubic interpolation functions, one for each dimension.

•

SplineInterpolation (corresponds to method = spline): Perform spline interpolation. By default, natural cubic spline interpolation is used. In the onedimensional case, $f$ is a piecewisecubic function passing through each data point$\left(x\,y\right)$ in the input. In this case, $f\left(u\right)$ = ${f}_{i}\left(u\right)$ if $u$ lies in the interval $\left[{x}_{i}\,{x}_{i+1}\right]$, where each ${f}_{i}$ is a cubic polynomial such that ${f}_{i}\left({x}_{i}\right)={y}_{i}$ and ${f}_{i}\left({x}_{i+1}\right)={y}_{i+1}$ for all data points $\left({x}_{i}\,{y}_{i}\right)$ in the input (where $i$ ranges from $0$ to $k$). The coefficients of the functions ${f}_{i}$ are selected such that $f$ is twice continuously differentiable ($\mathrm{C2}$), that is, ${f}_{i}\text{'}\left({x}_{i+1}\right)={f}_{i+1}\text{'}\left({x}_{i+1}\right)$and ${f}_{i}\text{'}\text{'}\left({x}_{i+1}\right)={f}_{i+1}\text{'}\text{'}\left({x}_{i+1}\right)$. In addition, the "natural" condition of the spline specifies that $f\text{'}\text{'}\left({x}_{0}\right)=0$ and $f\text{'}\text{'}\left({x}_{\mathrm{k}}\right)=0$. In the multidimensional case, $f$ is the tensor product of $n$ such spline functions, one for each dimension. Using SplineInterpolation will produce a smoother interpolant than CubicInterpolation ($\mathrm{C2}$ instead of $\mathrm{C1}$), but is more expensive to set up and more prone to numerical instability because each segment of the spline is determined globally by the positions of all other points in the data set.



Options


•

Options can be given either during construction of f, or while calling f. An option specified while calling f overrides one specified during construction of f.

•

If the option extrapolate=e is given, where e is of type extended_numeric or truefalse, then one of the following possible extrapolation methods will be used to compute $f\left(x\right)$ if $x$ lies outside the bounding box specified by the input:

–

extrapolate = true: Perform extrapolation using the closest valid branch of the interpolating function. In the case of LowestNeighborInterpolation and HighestNeighborInterpolation, this is not be defined for some points, in which case undefined will be returned.

–

extrapolate = false: Do not extrapolate. An error will be thrown if any point in xvalues lies outside the bounding box specified by the input.

–

extrapolate = e, where e is of type extended_numeric : Define $f\left(x\right)$ to be e if $x$ lies outside the bounding box specified by the input. e is commonly zero or undefined.


extrapolate=true is used by default.

•

If the option method=m is given, then it overrides the interpolation method specified by the procedure name. For example, $f\u2254\mathrm{LinearInterpolation}\left(\mathrm{xdata}\,\mathrm{ydata}\,'\mathrm{method}'='\mathrm{cubic}'\right)$ will return a cubic interpolation object, and $f\left(\mathrm{xvalues}\,'\mathrm{method}'='\mathrm{spline}'\right)$ will perform spline interpolation regardless of how $f$ was constructed.

•

If the options degree=d and endpoints=e are given, where d is a positive integer and e is one of natural, notaknot, or periodic, then spline interpolation will be performed using the provided degree and endpoint conditions. See Spline Continuity and End Conditions for details. These options only affect the result if SplineInterpolation is used; they are ignored otherwise. In the multidimensional case, the same degree and endpoint conditions are used for the splines generated in each dimension. The defaults are degree=3 and endpoints=natural, in which case natural cubic spline interpolation will be performed.

•

If splines of an even degree are being used, the option knots=data forces the use of a spline function where the spline knots are positioned on the nodes. See Spline Continuity and End Conditions for details. The default method, knots=default, defines the spline knots at the midpoints of the nodes when even degree splines are used. This option only affects SplineInterpolation calls; it is ignored for other objects.

•

When f is evaluated at a single point by supplying the coordinates directly, without a list or other container, Maple copies the values into a buffer that is reused between invocations. For the other calling sequence, where you supply a container with potentially multiple points, you can achieve similar behavior with the container option.


If the option container=c is given, where c is an appropriately sized rtable, then the computation is performed inplace and the result is returned in c. c must be of the correct size and datatype to match the output of the routine. With this option, no additional memory is allocated to store the result; this is a programmerlevel feature that can be used to reduce memory usage and decrease the time spent by Maple's garbage collector. The default is container=false, in which case Maple creates and returns a new rtable containing the result.

•

During construction of f, by default, Maple will sort the coordinates in xdata in each dimension, if they are not sorted already (and permute the entries in ydata accordingly). The data must be sorted for CurveFitting[ArrayInterpolation] to do its work. If you know that your data are sorted already, you can supply the verify = false option, which will disable this process; Maple will assume that the data are sorted.


During the call to f, by default, Maple will pass the option verify = false to the CurveFitting[ArrayInterpolation] command, because the sortedness of the data has already been verified. You can override this by passing verify = true, or just verify, to f.

•

If the option uniform=true is given, then Maple assumes that the data points are sampled over a grid of uniformly spaced points in each dimension. In other words, if ${a}_{i,j}$ is the $j$th possible coordinate in the $i$th dimension, then ${d}_{i}={a}_{i,j}{a}_{i,j1}$ is assumed to be constant over all possible $j$, given any fixed value of $i$. This gives a considerable speedup when the input contains uniform data, since it allows Maple to use a fast lookup algorithm when evaluating the interpolant at the specified points. Otherwise, Maple uses a slower but more general binary search algorithm to perform interpolation. Using the uniform=true option with nonuniform data may produce incorrect results.



Examples


>

$\mathrm{with}\left(\mathrm{Interpolation}\right)\:$

>

$\mathrm{with}\left(\mathrm{plots}\right)\:$

An introductory example. Suppose a signal is sampled several times over a given interval of time:
>

$\mathrm{Times}\u2254\left[0.\,0.01\,0.02\,0.03\,0.04\,0.05\,0.06\,0.07\,0.08\,0.09\,0.10\right]\:$

>

$\mathrm{Amplitudes}\u2254\left[0.6\,0.\,0.4\,0.6\,0.3\,0.1\,0.2\,0.\,0.1\,0.3\,0.6\right]\:$

>

$\mathrm{pointplot}\left(\mathrm{Times}\,\mathrm{Amplitudes}\right)$

To interpolate the data:
>

$f\u2254\mathrm{LinearInterpolation}\left(\mathrm{Times}\,\mathrm{Amplitudes}\right)$

${f}{\u2254}\left[\begin{array}{c}{\text{a linear interpolation object}}\\ {\text{with 11 points in 1D}}\end{array}\right]$
 (1) 
${0.510000000000000}$
 (2) 
>

$\mathrm{plot}\left(f\left(x\right)\,x=0...0.1\right)$

>

$\mathrm{NewTimes}\u2254\left[\mathrm{seq}\left(0.001i\,i=0..100\right)\right]$

${\mathrm{NewTimes}}{\u2254}\left[{0.}{\,}{0.001}{\,}{0.002}{\,}{0.003}{\,}{0.004}{\,}{0.005}{\,}{0.006}{\,}{0.007}{\,}{0.008}{\,}{0.009}{\,}{0.010}{\,}{0.011}{\,}{0.012}{\,}{0.013}{\,}{0.014}{\,}{0.015}{\,}{0.016}{\,}{0.017}{\,}{0.018}{\,}{0.019}{\,}{0.020}{\,}{0.021}{\,}{0.022}{\,}{0.023}{\,}{0.024}{\,}{0.025}{\,}{0.026}{\,}{0.027}{\,}{0.028}{\,}{0.029}{\,}{0.030}{\,}{0.031}{\,}{0.032}{\,}{0.033}{\,}{0.034}{\,}{0.035}{\,}{0.036}{\,}{0.037}{\,}{0.038}{\,}{0.039}{\,}{0.040}{\,}{0.041}{\,}{0.042}{\,}{0.043}{\,}{0.044}{\,}{0.045}{\,}{0.046}{\,}{0.047}{\,}{0.048}{\,}{0.049}{\,}{0.050}{\,}{0.051}{\,}{0.052}{\,}{0.053}{\,}{0.054}{\,}{0.055}{\,}{0.056}{\,}{0.057}{\,}{0.058}{\,}{0.059}{\,}{0.060}{\,}{0.061}{\,}{0.062}{\,}{0.063}{\,}{0.064}{\,}{0.065}{\,}{0.066}{\,}{0.067}{\,}{0.068}{\,}{0.069}{\,}{0.070}{\,}{0.071}{\,}{0.072}{\,}{0.073}{\,}{0.074}{\,}{0.075}{\,}{0.076}{\,}{0.077}{\,}{0.078}{\,}{0.079}{\,}{0.080}{\,}{0.081}{\,}{0.082}{\,}{0.083}{\,}{0.084}{\,}{0.085}{\,}{0.086}{\,}{0.087}{\,}{0.088}\right]$ 
  