Accelerating the pace of engineering and science

Documentation Center

• Trial Software

griddedInterpolant class

Gridded data interpolation

 Note:   The behavior of griddedInterpolant has changed. All interpolation methods now support extrapolation by default. Set F.ExtrapolationMethod to 'none' to preserve the pre-R2013a behavior when F.Method is 'linear', 'cubic' or 'nearest'. Before R2013a, evaluation returned NaN values at query points outside the domain when F.Method was set to 'linear', 'cubic' or 'nearest'.

Description

Use griddedInterpolant to perform interpolation on a 1-D, 2-D, 3-D, or N-D Gridded Data set. For example, you can pass a set of (x,y) points and values, v, to griddedInterpolant, and it returns a surface of the form v = F(x, y). This surface always passes through the sample values at the point locations. You can evaluate this surface at any query point, (xq,yq), to produce an interpolated value, vq.

Use griddedInterpolant to create the Interpolant, F. Then you can evaluate F at specific points using any of the following syntaxes:

• Vq = F(Xq) evaluates F at a set of query points in matrix Xq. The points in Xq are scattered, and each row of Xq contains the coordinates of a query point.

• Vq = F(xq1,xq2,...,xqn) specifies the query locations, xq1,xq2,...,xqn, as column vectors of length m representing m points scattered in n-dimensional space.

• Vq = F(Xq1,Xq2,...,Xqn) specifies the query locations as n n-dimensional arrays, Xq1,Xq2,...,Xqn, of equal size which define a Full Grid of points.

• Vq = F({xgq1,xgq2,...,xgqn}) specifies the query locations as Grid Vectors . Use this syntax to conserve memory when you want to query a large grid of points.

Construction

F = griddedInterpolant(x,v) creates a 1-D interpolant from a vector of sample points, x, and corresponding values, v.

F = griddedInterpolant(X1,X2,...,Xn,V) creates a 2-D, 3-D, or N-D interpolant using a Full Grid of sample points passed as a set of n-dimensional arrays, X1,X2,...,Xn. The V array contains the sample values associated with the point locations in X1,X2,...,Xn. Each of the arrays, X1,X2,...,Xn must be the same size as V.

F = griddedInterpolant(V) uses the default grid to create the interpolant. When you use this syntax, griddedInterpolant defines the grid as set of points whose spacing is 1 and range is [1, size(V,i)] in the ith dimension. Use this syntax to when you want to conserve memory and are not concerned about the absolute distances between points.

F = griddedInterpolant({xg1,xg2,...,xgn},V) specifies n Grid Vectors to describe an n-dimensional grid of sample points. Use this syntax when you want to use a specific grid and also conserve memory.

F = griddedInterpolant(___,Method) specifies any of five strings that describe an interpolation method: 'linear', 'nearest', 'pchip', 'cubic', or 'spline'. You can specify Method as the last input argument in any of the first four syntaxes.

F = griddedInterpolant(___,Method,ExtrapolationMethod) specifies both the interpolation and extrapolation methods as strings. griddedInterpolant uses ExtrapolationMethod to estimate the value when your query points fall outside the domain of your sample points. Specify Method and ExtrapolationMethod together as the last two input arguments in any of the first four syntaxes.

Input Arguments

x

Sample points vector, specified as a vector of input coordinates the same size as v.

v

Sample values vector, specified as a vector of input values the same size as x.

X1,X2,...,Xn

Sample points in Full Grid form, specified as a set of n-dimensional arrays. You can create the arrays, X1,X2,...,Xn, using the ndgrid function. These arrays are all the same size, and each one is the same size as V.

{xg1,xg2,...,xgn}

Sample points in grid vector form, specified as a cell array of grid vectors. These vectors must specify a grid that is the same size as V. In other words, size(V) = [length(xg1) length(xg2),...,length(xgn)]. Use this form as an alternative to the full grid to save memory when your grid is very large.

V

Sample values, specified as an array. The elements of V are the values that correspond to the sample points. The size of V must be the size of the full grid of sample points.

• If you specify the sample points as a full grid consisting of N-D arrays, then V must be the same size as any one of: X1,X2,...,Xn.

• If you specify the sample points as grid vectors, then size(V) = [length(xg1) length(xg2) ... length(xgn)].

Method

Interpolation method, specified as a string from the table below.

'linear'(default)The interpolated value at a query point is based on linear interpolation of the values at neighboring grid points in each respective dimension. C0
• Requires at least 2 grid points in each dimension.

• Requires more memory than 'nearest'.

'nearest'The interpolated value at a query point is the value at the nearest sample grid point. Discontinuous
• Requires 2 grid points in each dimension.

• Fastest computation with modest memory requirements

'pchip'Shape-preserving piecewise cubic interpolation (for 1-D only). The interpolated value at a query point is based on a shape-preserving piecewise cubic interpolation of the values at neighboring grid points.C1
• Requires at least 4 points.

• Requires more memory and computation time than 'linear'.

'cubic'The interpolated value at a query point is based on a cubic interpolation of the values at neighboring grid points in each respective dimension. The interpolation is based on a cubic convolution.C1
• Grid must have uniform spacing, though the spacing in each dimension does not have to be the same.

• Requires at least 4 points in each dimension.

• Requires more memory and computation time than 'linear'.

'spline'The interpolated value at a query point is based on a cubic interpolation of the values at neighboring grid points in each respective dimension. The interpolation is based on a cubic spline.C2
• Requires 4 points in each dimension.

• Requires more memory and computation time than 'cubic'.

ExtrapolationMethod

Extrapolation method, specified as any of the Method choices: 'linear', 'nearest', 'pchip', 'cubic', or 'spline'. In addition, you can specify 'none' if you want queries outside the domain of your grid return NaN values.

If you omit ExtrapolationMethod, the default value is the string you specify for Method. If you omit both the Method and ExtrapolationMethod arguments, both default to 'linear'.

Properties

 GridVectors Cell array containing grid vectors, {xg1,xg2,...,xgn}. These vectors specify the grid points (locations) for the values in F.Values. Values Array of values associated with the grid points in F.GridVectors. Method A string specifying the name of a method used to interpolate the data. Method is one of five strings: 'linear', 'nearest', 'pchip', 'cubic', or 'spline'. The default value is 'linear'. ExtrapolationMethod A string specifying the name of a method used to extrapolate the data. ExtrapolationMethod is one of six strings: 'linear', 'nearest', 'pchip', 'cubic', 'spline', or 'none'. A value of 'none' indicates that extrapolation is disabled. The default value is the value of F.Method.

Definitions

Interpolant

Interpolating function that you can evaluate at query locations.

Gridded Data

A set of points that are axis-aligned and ordered.

Scattered Data

A set of points that have no structure among their relative locations.

Full Grid

A grid represented as a set of arrays. For example, you can create a full grid using ndgrid.

Grid Vectors

A set of vectors that serve as a compact representation of a grid in ndgrid format. For example, [X,Y] = ndgrid(xg,yg) returns a full grid in the matrices X and Y. You can represent the same grid using the grid vectors, xg and yg.

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB® documentation.

Indexing

Index-based editing of the properties of F are not supported. Instead, wholly replace the GridVectors or Values arrays as necessary. See Interpolation with the griddedInterpolant Class in the MATLAB Mathematics documentation for more information.

Examples

expand all

2-D Interpolation Over Finer Grid

Interpolate coarsely sampled data using a full grid with spacing of 0.5.

Define the sample points as a full grid with range [1, 10] in both dimensions.

```[X,Y] = ndgrid(1:10,1:10);
```

Sample f(x,y) = x2+y2 at the grid points.

```V = X.^2 + Y.^2;
```

Create the interpolant, specifying cubic interpolation.

```F = griddedInterpolant(X,Y,V,'cubic');
```

Define a full grid of query points with 0.5 spacing and evaluate the interpolant at those points. Then plot the result.

```[Xq,Yq] = ndgrid(1:0.5:10,1:0.5:10);
Vq = F(Xq,Yq);
mesh(Xq,Yq,Vq);
```

1-D Extrapolation

Compare results of querying the interpolant outside the domain of F using the 'pchip' and 'nearest' extrapolation methods.

Create the interpolant and specify 'pchip' as the interpolation method.

```x = [1 2 3 4 5];
v = [12 16 31 10 6];
F = griddedInterpolant(x,v,'pchip')```
```F =

griddedInterpolant with properties:

GridVectors: {[1 2 3 4 5]}
Values: [12 16 31 10 6]
Method: 'pchip'
ExtrapolationMethod: 'pchip'
```

Query the interpolant, and include points outside the domain of F.

```xq = 0:0.1:6;
vq = F(xq);
figure
plot(x,v,'o',xq,vq,'-b');
legend ('v','vq')```

Query the interpolant at the same points again, using the nearest neighbor extrapolation method.

```F.ExtrapolationMethod = 'nearest';
figure
vq = F(xq);
plot(x,v,'o',xq,vq,'-b');
legend ('v','vq')
```