naginterfaces.library.interp.dimn_​grid

naginterfaces.library.interp.dimn_grid(narr, uniform, axis, v, point, method, k=1, wf=0.0)

dimn_grid interpolates data at a point in $n$-dimensional space, that is defined by a set of gridded data points. It offers three methods to interpolate the data: Linear Interpolation, Cubic Interpolation and Weighted Average.

For full information please refer to the NAG Library document for e01za

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/e01/e01zaf.html

Parameters

narrint, array-like, shape $\left(d\right)$

The number of data ordinates in each dimension, with $narr[\text{i}-1]=n_i$, for $\text{i}=1,2,\dots ,d$.

uniformbool

States whether the data points are uniformly spaced.

$uniform=True$

The data points are uniformly spaced.

$uniform=False$

The data points are not uniformly spaced.

axisfloat, array-like, shape $\left(\text{lx}\right)$

Defines the axis. If the data points are uniformly spaced (see argument $uniform$) $axis$ should contain the start and end of each dimension $(x_{11},x_{1n_1},\dots ,x_{d1},x_{d{n}_d})$.

If the data points are not uniformly spaced, $axis$ should contain all the data ordinates for each dimension $(x_{11},x_{12},\dots ,x_{1n_1},\dots ,x_{d1},x_{d2},\dots ,x_{d{n}_d})$.

vfloat, array-like, shape $\left(prod\left(narr\right)\right)$

Holds the values of the data points in such an order that the index of a data value with coordinates $(z_1,z_2,\dots ,z_d)$ is

$$\sum _1^d{z}_{\text{i}}\prod _{n\in S_i}n\text{,}$$

where $S_i=\left\{narr\right[l-1]:l=1,\dots ,i-1\}$ e.g., $((x_{11},x_{21},\dots ,x_{d1}),(x_{12},x_{21},\dots ,x_{d1}),\dots ,(x_{1n_d},x_{21},\dots ,x_{d1}),(x_{11},x_{22},\dots ,x_{d1}),(x_{12},x_{22},\dots ,x_{d1}),\dots ,(x_{1n_d},x_{2n_d},\dots ,x_{d{n}_d}))$.

pointfloat, array-like, shape $\left(d\right)$

$x$, the point at which the data value is to be interpolated.

methodint

The method to be used.

$method=1$

Weighted Average.

$method=2$

Linear Interpolation.

$method=3$

Cubic Interpolation.

kint, optional

If $method=1$, $k$ controls the number of data points used in the Weighted Average method, with $k$ points used in each dimension, either side of the interpolation point. The total number of data points used for the interpolation will, therefore, be ${\left(2k\right)}^d$.

If $method\ne 1$, then $k$ is not referenced and need not be set.

wffloat, optional

The power used for the weighted average such that a high power will cause closer points to be more heavily weighted.

Returns

ansfloat

Holds the result of the interpolation.

Raises

NagValueError

(errno $1$)

On entry, $d=⟨value⟩$.

Constraint: $d\ge 2$.

(errno $2$)

On entry, $narr[⟨value⟩]=⟨value⟩$.

Constraint: $narr[\text{i}-1]\ge 2$.

(errno $4$)

On entry, $axis$ decreases in dimension $⟨value⟩$.

Constraint: $axis$ definition must be strictly increasing.

(errno $5$)

On entry, $\text{lx}=⟨value⟩$, sum of $narr$$=⟨value⟩$.

Constraint: if $uniform=False$, $\text{lx}=$ sum of $narr$.

(errno $5$)

On entry, $\text{lx}=⟨value⟩$, $d=⟨value⟩$.

Constraint: if $uniform=True$, $\text{lx}=2d$.

(errno $7$)

On entry, $k=⟨value⟩$.

Constraint: if $method=1$, $k\ge 1$.

(errno $8$)

On entry, $point[⟨value⟩]=⟨value⟩$ and data range $=[⟨value⟩,⟨value⟩]$.

Constraint: $point$ must be within the data range.

(errno $9$)

On entry, $method=3$ and $uniform=False$.

Constraint: if $method=3$, $uniform$ must be $True$.

(errno $9$)

On entry, $method=⟨value⟩$.

Constraint: $method=1$, $2$ or $3$.

(errno $10$)

On entry, $wf=⟨value⟩$.

Constraint: if $method=1$, $1.0\le wf\le 15.0$.

(errno $101$)

Cubic Interpolation method does not have enough data surrounding $point$; interpolation not possible.

Warns

NagAlgorithmicWarning

(errno $201$)

Warning: the size of $k$ has been reduced, due to too few data points around $point$.

Notes

dimn_grid interpolates an $n$-dimensional point within a set of gridded data points, $Z=\{z_{1j_1},z_{2j_2},\dots ,z_{d{j}_d}\}$, with corresponding data values $F=\{f_{1j_1},f_{2j_2},\dots ,f_{d{j}_d}\}$ where, for the $i$th dimension, $j_i=1,\dots ,n_i$ and $n_i$ is the number of ordinates in the $i$th dimension.

A hypercube of ${\left(2k\right)}^d$ data points $[h_1,h_2,\dots ,h_{{\left(2k\right)}^d}]\subset Z$, where $h_i=(h_{i1},h_{i2},\dots ,h_{id})$ and the corresponding data values are $f\left(h_i\right)\in F$, around the given point, $x=(x_1,x_2,\dots ,x_d)$, is found and then used to interpolate using one of the following three methods.

1. Weighted Average, that is a modification of Shepard’s method (Shepard (1968)) as used for scattered data in dimn_scat_shep(). This method interpolates the data with the weighted mean

   $$Q\left(x\right)=\frac{{\sum }_{r=1}^{{\left(2k\right)}^d}{w}_r\left(x\right)f_r}{{\sum }_{r=1}^{{\left(2k\right)}^d}{w}_r\left(x\right)}\text{,}$$

   where $f_r=f\left(h_r\right)$, $w_r\left(x\right)=\frac{1}{D\left(|x-h_r|\right)}$ and $D\left(y\right)=y_1^{\rho }+y_2^{\rho }+\cdots +y_d^{\rho }$, for a given value of $\rho$.

2. Linear Interpolation, which takes $2^d$ surrounding data points ($k=1$) and performs two one-dimensional linear interpolations in each dimension on data points $h_a$ and $h_b$, reducing the dimension every iteration until it has reached an answer. The formula for linear interpolation in dimension $i$ is simply

   $$f=f_a+(x_i-h_{ai})\frac{f_b-f_a}{h_{bi}-h_{ai}}\text{,}$$

   where $f_r=f\left(h_r\right)$ and $h_{ai}<x_i<h_{bi}$.

3. Cubic Interpolation, based on cubic convolution (Keys (1981)). In a similar way to the Linear Interpolation method, it performs the interpolations in one dimension reducing it each time, however it requires four surrounding data points in each dimension ($k=2$), two in each direction $(h_{-1},h_0,h_1,h_2)$. The following is used to calculate the one-dimensional interpolant in dimension $i$

   $$\begin{array}{c}f=\frac{1}{2}\left(\begin{array}{cccc}1& t& t^2& t^3\end{array}\right)\left(\begin{array}{cccc}0& 2& 0& 0\\ -1& 0& 1& 0\\ 2& -5& 4& -1\\ -1& 3& -3& 1\end{array}\right)\left(\begin{array}{c}{f}_{-1}\\ f_0\\ f_1\\ f_2\end{array}\right)\end{array}$$

   where $t=x_i-h_{0i}$ and $f_r=f\left(h_r\right)$.

References

Keys, R, 1981, Cubic Convolution Interpolation for Digital Image Processing, IEEE Transactions on Acoutstics, Speech, and Signal Processing (Vol ASSP-29 No. 6), 1153–1160, http://hmi.stanford.edu/doc/Tech_Notes/HMI-TN-2004-004-Interpolation/Keys_cubic_interp.pdf

Shepard, D, 1968, A two-dimensional interpolation function for irregularly spaced data, Proc. 23rd Nat. Conf. ACM, 517–523, Brandon/Systems Press Inc., Princeton