Gridded data interpolation
expand all in page
Description
Use griddedInterpolant
to perform interpolation on a 1D, 2D, 3D, or ND gridded data set. griddedInterpolant
returns the interpolant F
for the given data set. You can evaluate F
at a set of query points, such as (xq,yq)
in 2D, to produce interpolated values vq = F(xq,yq)
.
Use scatteredInterpolant to perform interpolation with scattered data.
Creation
Syntax
F = griddedInterpolant
F = griddedInterpolant(x,v)
F = griddedInterpolant(X1,X2,...,Xn,V)
F = griddedInterpolant(V)
F = griddedInterpolant(gridVecs,V)
F = griddedInterpolant(___,Method)
F = griddedInterpolant(___,Method,ExtrapolationMethod)
Description
creates an empty gridded data interpolant object.F
= griddedInterpolant
example
creates a 1D interpolant from a vector of sample points F
= griddedInterpolant(x,v)x
and corresponding values v
.
example
creates a 2D, 3D, or ND interpolant using a full grid of sample points passed as a set of F
= griddedInterpolant(X1,X2,...,Xn,V)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
.
example
uses the default grid to create the interpolant. When you use this syntax, F
= griddedInterpolant(V)griddedInterpolant
defines the grid as a set of points whose spacing is 1
and range is [1
, size(V,i)
] in the i
th dimension. Use this syntax when you want to conserve memory and are not concerned about the absolute distances between points.
example
specifies a cell array F
= griddedInterpolant(gridVecs,V)gridVecs
that contains 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.
example
specifies the interpolation method: F
= griddedInterpolant(___,Method)'linear'
, 'nearest'
, 'next'
, 'previous'
, 'pchip'
, 'cubic'
, 'makima'
, or 'spline'
. You can specify Method
as the last input argument in any of the previous syntaxes.
example
specifies both the interpolation and extrapolation methods. F
= griddedInterpolant(___,Method,ExtrapolationMethod)griddedInterpolant
uses ExtrapolationMethod
to estimate the value when your query points fall outside the domain of your sample points.
Input Arguments
expand all
x
— Sample points
vector
Sample points, specified as a vector. x
and v
must be the same size. The sample points in x
must be unique.
Data Types: single
 double
v
— Sample values
vector  matrix  multidimensional array
Sample values, specified as a vector, matrix, or multidimensional array. The elements of v
are the values that correspond to the sample points in x
.
To interpolate using a single set of values,
x
andv
must be vectors of the same length.To interpolate using multiple sets of values,
v
can be an array with extra dimensions compared tox
. The size of the first dimension ofv
must match the number of sample points inx
, and each column inv
defines a separate set of 1D values. For example, ifx
is a column vector with 10 elements, you can specifyv
as a 10by4 matrix to interpolate using four different sets of values.
Data Types: single
 double
X1
, X2
, Xn
— Sample points in full grid form
arrays
Sample points in full grid form, specified as separate n
dimensional arrays. The sample points must be unique and sorted. 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
.
Data Types: single
 double
gridVecs
— Sample points in grid vector form
cell array of grid vectors
Sample points in grid vector form, specified as a cell array of grid vectors {xg1,xg2,...,xgn}
. The sample points must be unique and sorted. The 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.
Data Types: single
 double
V
— Sample values
array
Sample values, specified as an array. The elements of V
are the values that correspond to the sample points. The first N
dimensions of V
must have the same sizes as the corresponding dimensions in the full grid of sample points, where N
is the number of dimensions of the grid.
To interpolate using a single set of values, specify
V
as an array with the same size as the full grid of sample points. For example, if the sample points form a grid with size 100by100, you can specify the values with a matrix of the same size.To interpolate using multiple sets of values, specify
V
as an array with extra dimensions compared to the grid of sample points. The extra dimensions define multiple values at each sample point. For example, if the sample points form a grid with size 100by100, you can specify the values as an array with size 100by100by4 to interpolate using four different sets of 100by100 values.
Data Types: single
 double
Method
— Interpolation method
'linear'
(default)  'nearest'
 'next'
 'previous'
 'pchip'
 'cubic'
 'spline'
 'makima'
Interpolation method, specified as one of the options in this table.
Method  Description  Continuity  Comments 

'linear' (default)  Linear interpolation. The interpolated value at a query point is based on linear interpolation of the values at neighboring grid points in each respective dimension.  C^{0} 

'nearest'  Nearest neighbor interpolation. The interpolated value at a query point is the value at the nearest sample grid point.  Discontinuous 

'next'  Next neighbor interpolation (for 1D only). The interpolated value at a query point is the value at the next sample grid point.  Discontinuous 

'previous'  Previous neighbor interpolation (for 1D only). The interpolated value at a query point is the value at the previous sample grid point.  Discontinuous 

'pchip'  Shapepreserving piecewise cubic interpolation (for 1D only). The interpolated value at a query point is based on a shapepreserving piecewise cubic interpolation of the values at neighboring grid points.  C^{1} 

'cubic'  Cubic interpolation. 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.  C^{1} 

'makima'  Modified Akima cubic Hermite interpolation. The interpolated value at a query point is based on a piecewise function of polynomials with degree at most three evaluated using the values of neighboring grid points in each respective dimension. The Akima formula is modified to avoid overshoots.  C^{1} 

'spline'  Cubic spline interpolation. 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 using notaknot end conditions.  C^{2} 

ExtrapolationMethod
— Extrapolation method
'linear'
(default)  'nearest'
 'next'
 'previous'
 'pchip'
 'cubic'
 'spline'
 'makima'
 'none'
Extrapolation method, specified as 'linear'
, 'nearest'
, 'next'
, 'previous'
, 'pchip'
, 'cubic'
, 'spline'
, or 'makima'
. In addition, you can specify 'none'
if you want queries outside the domain of your grid to return NaN
values.
If you omit ExtrapolationMethod
, the default is the value you specify for Method. If you omit both the Method
and ExtrapolationMethod
arguments, both values default to 'linear'
.
Properties
expand all
GridVectors
— Grid vectors
cell array
Grid vectors, specified as a cell array {xg1,xg2,...,xgn}
. These vectors specify the grid points (locations) for the values in Values
. The grid points must be unique.
Data Types: cell
Values
— Function values at sample points
array
Function values at sample points, specified as an array of values associated with the grid points in GridVectors
.
Data Types: single
 double
Method
— Interpolation method
'linear'
(default)  'nearest'
 'next'
 'previous'
 'pchip'
 'cubic'
 'spline'
 'makima'
Interpolation method, specified as a character vector. Method
can be: 'linear'
, 'nearest'
, 'next'
, 'previous'
, 'pchip'
, 'cubic'
, 'spline'
, or 'makima'
. See Method for descriptions of these methods.
Data Types: char
ExtrapolationMethod
— Extrapolation method
'linear'
 'nearest'
 'next'
 'previous'
 'pchip'
 'cubic'
 'spline'
 'makima'
 'none'
Extrapolation method, specified as a character vector. ExtrapolationMethod
can be: 'linear'
, 'nearest'
, 'next'
, 'previous'
, 'pchip'
, 'cubic'
, 'spline'
, 'makima'
, or 'none'
. A value of 'none'
indicates that extrapolation is disabled. The default value is the value of Method.
Data Types: char
Usage
Syntax
Vq = F(Xq)
Vq = F(xq1,xq2,...,xqn)
Vq = F(Xq1,Xq2,...,Xqn)
Vq = F({xgq1,xgq2,...,xgqn})
Description
Use griddedInterpolant
to create the interpolant, F
. Then you can evaluate F
at specific query points using any of the following syntaxes:
Vq = F(Xq)
specifies the query points in the matrix Xq
. Each row of Xq
contains the coordinates of a query point.
Vq = F(xq1,xq2,...,xqn)
specifies the query points 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 points using the n
dimensional arrays Xq1,Xq2,...,Xqn
, which define a full grid of points.
Vq = F({xgq1,xgq2,...,xgqn})
specifies the query points as grid vectors. Use this syntax to conserve memory when you want to query a large grid of points.
Examples
collapse all
1D Interpolation
Open Live Script
Use griddedInterpolant
to interpolate a 1D data set.
Create a vector of scattered sample points v
. The points are sampled at random 1D locations between 0 and 20.
x = sort(20*rand(100,1));v = besselj(0,x);
Create a gridded interpolant object for the data. By default, griddedInterpolant
uses the 'linear'
interpolation method.
F = griddedInterpolant(x,v)
F = griddedInterpolant with properties: GridVectors: {[100x1 double]} Values: [100x1 double] Method: 'linear' ExtrapolationMethod: 'linear'
Query the interpolant F
at 500 uniformly spaced points between 0 and 20. Plot the interpolated results (xq,vq)
on top of the original data (x,v)
.
xq = linspace(0,20,500);vq = F(xq);plot(x,v,'ro')hold onplot(xq,vq,'.')legend('Sample Points','Interpolated Values')
3D Interpolation Using Full Grid vs. Grid Vectors
Open Live Script
Interpolate 3D data using two methods to specify the query points.
Create and plot a 3D data set representing the function $\mathit{z}\left(\mathit{x},\mathit{y}\right)=\frac{\mathrm{sin}\left({\mathit{x}}^{2}+{\mathit{y}}^{2}\right)}{{\mathit{x}}^{2}+{\mathit{y}}^{2}}$ evaluated at a set of gridded sample points in the range [5,5].
[x,y] = ndgrid(5:0.8:5);z = sin(x.^2 + y.^2) ./ (x.^2 + y.^2);surf(x,y,z)
Create a gridded interpolant object for the data.
F = griddedInterpolant(x,y,z);
Use a finer mesh to query the interpolant and improve the resolution.
[xq,yq] = ndgrid(5:0.1:5);vq = F(xq,yq);surf(xq,yq,vq)
In cases where there are a lot of sample points or query points, and where memory usage becomes a concern, you can use grid vectors to improve memory usage.
When you specify grid vectors instead of using
ndgrid
to create the full grid,griddedInterpolant
avoids forming the full query grid to carry out the calculations.When you pass grid vectors, they are normally grouped together as cells in a cell array,
{xg1, xg2, ..., xgn}
. The grid vectors are a compact way to represent the points of the full grid.
Alternatively, execute the previous commands using grid vectors.
x = 5:0.8:5;y = x';z = sin(x.^2 + y.^2) ./ (x.^2 + y.^2);F = griddedInterpolant({x,y},z);xq = 5:0.1:5;yq = xq';vq = F({xq,yq});surf(xq,yq,vq)
Interpolation with Default Grid
Open Live Script
Use the default grid to perform a quick interpolation on a set of sample points. The default grid uses unitspaced points, so this interpolation is useful when the exact xy spacing between the sample points is not important.
Create a matrix of sample function values and plot them against the default grid.
x = (1:0.3:5)';y = x';V = cos(x) .* sin(y);n = length(x);surf(1:n,1:n,V)
Interpolate the data using the default grid.
F = griddedInterpolant(V)
F = griddedInterpolant with properties: GridVectors: {[1 2 3 4 5 6 7 8 9 10 11 12 13 14] [1 2 3 4 5 6 7 8 9 10 11 12 13 14]} Values: [14x14 double] Method: 'linear' ExtrapolationMethod: 'linear'
Query the interpolant and plot the results.
[xq,yq] = ndgrid(1:0.2:n);Vq = F(xq,yq);surf(xq',yq',Vq)
2D Interpolation over Finer Grid
Open Live Script
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)={x}^{2}+{y}^{2}$$ 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);
1D Extrapolation
Open Live Script
Compare results of querying the interpolant outside the domain of F
using the 'pchip'
and 'nearest'
extrapolation methods.
Create the interpolant, specifying 'pchip'
as the interpolation method and 'nearest'
as the extrapolation method.
x = [1 2 3 4 5];v = [12 16 31 10 6];F = griddedInterpolant(x,v,'pchip','nearest')
F = griddedInterpolant with properties: GridVectors: {[1 2 3 4 5]} Values: [12 16 31 10 6] Method: 'pchip' ExtrapolationMethod: 'nearest'
Query the interpolant, and include points outside the domain of F
.
xq = 0:0.1:6;vq = F(xq);figureplot(x,v,'o',xq,vq,'b');legend ('v','vq')
Query the interpolant at the same points again, this time using the 'pchip'
extrapolation method.
F.ExtrapolationMethod = 'pchip';figurevq = F(xq);plot(x,v,'o',xq,vq,'b');legend ('v','vq')
Interpolate Multiple Sets of Values on Same Grid
Open Live Script
Use griddedInterpolant
to interpolate three different sets of values at the same query points.
Create a grid of sample points with $5\le \mathit{X}\le 5$ and $3\le \mathit{Y}\le 3$.
gx = 5:5;gy = 3:3;[X,Y] = ndgrid(gx,gy);
Evaluate three different functions at the query points, and then concatenate the values into a 3D array. The size of V
is the same as the X
and Y
grids in the first two dimensions, but the size of the extra dimension reflects the number of values associated with each sample point (in this case, three).
f1 = X.^2 + Y.^2;f2 = X.^3 + Y.^3;f3 = X.^4 + Y.^4;V = cat(3,f1,f2,f3);
Create an interpolant using the sample points and associated values.
F = griddedInterpolant(X,Y,V);
Create a grid of query points with a finer mesh size compared to the sample points.
qx = 5:0.4:5;qy = 3:0.4:3;[XQ,YQ] = ndgrid(qx,qy);
Interpolate all three sets of values at the query points.
VQ = F(XQ,YQ);
Compare the original data with the interpolated results.
tiledlayout(3,2)nexttilesurf(X,Y,f1)title('f1')nexttilesurf(XQ,YQ,VQ(:,:,1))title('Interpolated f1')nexttilesurf(X,Y,f2)title('f2')nexttilesurf(XQ,YQ,VQ(:,:,2))title('Interpolated f2')nexttilesurf(X,Y,f3)title('f3')nexttilesurf(XQ,YQ,VQ(:,:,3))title('Interpolated f3')
More About
expand all
Interpolant
Interpolating function that you can evaluate at query points.
Gridded Data
A set of points that are axisaligned 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
.
Tips
It is quicker to evaluate a
griddedInterpolant
objectF
at many different sets of query points than it is to compute the interpolations separately usinginterp1
,interp2
,interp3
, orinterpn
. For example:% Fast to create interpolant F and evaluate multiple timesF = griddedInterpolant(X1,X2,V)v1 = F(Xq1)v2 = F(Xq2)% Slower to compute interpolations separately using interp2v1 = interp2(X1,X2,V,Xq1)v2 = interp2(X1,X2,V,Xq2)
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
Dimension of the query points and dimensions of the input gridded data must be compile time constant.
Method
andExtrapolationMethod
must be constants (known values when code is generated).Code generation does not support the makima function for 2D, 3D, or ND interpolations.
Empty interpolant objects are not supported for code generation.
If the
Values
property ofgriddedInterpolant
is variablesize, is not a variablelength vector, and becomes a row vector at run time, then an error occurs.If the sample values or query points contain
Inf
orInf
, the output of the generated code might not match the output in MATLAB^{®}.
ThreadBased Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
This function fully supports threadbased environments. For more information, see Run MATLAB Functions in ThreadBased Environment.
GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.
Usage notes and limitations:
For 1D interpolants, supported interpolation methods are
'cubic'
,'linear'
,'nearest'
,'next'
,'previous'
, and'spline'
.For 2D interpolants, supported interpolation methods are
'cubic'
,'linear'
, and'nearest'
.For 3D and higher dimensional interpolants, supported interpolation methods are
'linear'
and'nearest'
.6D or higher dimensional interpolants are not supported.
Interpolation method
'spline'
is not supported when sample values argumentV
containsNaN
values.Extrapolation method
'spline'
is only supported when using the'spline'
interpolation method.Extrapolation method
'cubic'
is only supported when using'cubic'
or'spline'
interpolation methods.
For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).
Version History
Introduced in R2011b
expand all
R2021a: Interpolate multiple data sets simultaneously
Support added to interpolate multiple data sets on the same grid at the same query points. For example, if you specify a 2D grid, a 3D array of values at the grid points, and a 2D collection of query points, then griddedInterpolant
returns the interpolated values at the query points for each 2D page in the 3D array of values.
Previously, this functionality was available in interp1
for 1D interpolation, but this improvement to griddedInterpolant
adds support for ND multivalued interpolation.
See Also
scatteredInterpolant  interp1  interp2  interp3  interpn  ndgrid  meshgrid  fillmissing  filloutliers
Topics
 Resample Image with Gridded Interpolation
 Interpolating Gridded Data
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 Deutsch
 English
 Français
 United Kingdom (English)
Contact your local office