@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 2007 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Interpolation
@chapter Interpolation

Octave provides the following functions for interpolation.

@anchor{doc-interp1}
@deftypefn {Function File} {@var{yi} =} interp1 (@var{x}, @var{y}, @var{xi})
@deftypefnx {Function File} {@var{yi} =} interp1 (@dots{}, @var{method})
@deftypefnx {Function File} {@var{yi} =} interp1 (@dots{}, @var{extrap})
@deftypefnx {Function File} {@var{pp} =} interp1 (@dots{}, 'pp')

One-dimensional interpolation. Interpolate @var{y}, defined at the
points @var{x}, at the points @var{xi}. The sample points @var{x} 
must be strictly monotonic. If @var{y} is an array, treat the columns
of @var{y} seperately.

Method is one of:

@table @asis
@item 'nearest'
Return the nearest neighbour.
@item 'linear'
Linear interpolation from nearest neighbours
@item 'pchip'
Piece-wise cubic hermite interpolating polynomial
@item 'cubic'
Cubic interpolation from four nearest neighbours
@item 'spline'
Cubic spline interpolation--smooth first and second derivatives
throughout the curve
@end table

Appending '*' to the start of the above method forces @code{interp1}
to assume that @var{x} is uniformly spaced, and only @code{@var{x}
(1)} and @code{@var{x} (2)} are referenced. This is usually faster,
and is never slower. The default method is 'linear'.

If @var{extrap} is the string 'extrap', then extrapolate values beyond
the endpoints.  If @var{extrap} is a number, replace values beyond the
endpoints with that number.  If @var{extrap} is missing, assume NaN.

If the string argument 'pp' is specified, then @var{xi} should not be
supplied and @code{interp1} returns the piece-wise polynomial that
can later be used with @code{ppval} to evaluate the interpolation.
There is an equivalence, such that @code{ppval (interp1 (@var{x},
@var{y}, @var{method}, 'pp'), @var{xi}) == interp1 (@var{x}, @var{y},
@var{xi}, @var{method}, 'extrap')}.

An example of the use of @code{interp1} is

@example
@group
   xf=[0:0.05:10]; yf = sin(2*pi*xf/5);
   xp=[0:10];      yp = sin(2*pi*xp/5);
   lin=interp1(xp,yp,xf);
   spl=interp1(xp,yp,xf,'spline');
   cub=interp1(xp,yp,xf,'cubic');
   near=interp1(xp,yp,xf,'nearest');
   plot(xf,yf,';original;',xf,lin,';linear;',xf,spl,';spline;',...
        xf,cub,';cubic;',xf,near,';nearest;',xp,yp,'*;;');
@end group
@end example

@seealso{interpft}
@end deftypefn


@anchor{doc-interp2}
@deftypefn {Function File} {@var{zi}=} interp2 (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi})
@deftypefnx {Function File} {@var{zi}=} interp2 (@var{Z}, @var{xi}, @var{yi})
@deftypefnx {Function File} {@var{zi}=} interp2 (@var{Z}, @var{n})
@deftypefnx {Function File} {@var{zi}=} interp2 (@dots{}, @var{method})
@deftypefnx {Function File} {@var{zi}=} interp2 (@dots{}, @var{method}, @var{extrapval})

Two-dimensional interpolation. @var{x}, @var{y} and @var{z} describe a
surface function. If @var{x} and @var{y} are vectors their length
must correspondent to the size of @var{z}. @var{x} and @var{Yy} must be
monotonic. If they are matrices they  must have the @code{meshgrid} 
format. 

@table @code
@item interp2 (@var{x}, @var{y}, @var{Z}, @var{xi}, @var{yi}, @dots{}) 
Returns a matrix corresponding to the points described by the
matrices  @var{XI}, @var{YI}. 

If the last argument is a string, the interpolation method can
be specified. The method can be 'linear', 'nearest' or 'cubic'.
If it is omitted 'linear' interpolation  is assumed.

@item  interp2 (@var{z}, @var{xi}, @var{yi})
Assumes @code{@var{x} = 1:rows (@var{z})} and @code{@var{y} = 
1:columns (@var{z})}

@item interp2 (@var{z}, @var{n}) 
Interleaves the Matrix @var{z} n-times. If @var{n} is ommited a value
of @code{@var{n} = 1} is assumed.
@end table

The variable @var{method} defines the method to use for the
interpolation. It can take one of the values

@table @asis
@item 'nearest'
Return the nearest neighbor.
@item 'linear'
Linear interpolation from nearest neighbors.
@item 'pchip'
Piece-wise cubic hermite interpolating polynomial (not implemented yet).
@item 'cubic'
Cubic interpolation from four nearest neighbors.
@item 'spline'
Cubic spline interpolation--smooth first and second derivatives
throughout the curve (not implemented yet).
@end table

If a scalar value @var{extrapval} is defined as the final value, then
values outside the mesh as set to this value. Note that in this case 
@var{method} must be defined as well. If @var{extrapval} is not
defined then NaN is assumed. 

@seealso{interp1}
@end deftypefn


@anchor{doc-interpft}
@deftypefn {Function File} {} interpft (@var{x}, @var{n})
@deftypefnx {Function File} {} interpft (@var{x}, @var{n}, @var{dim})

Fourier interpolation. If @var{x} is a vector, then @var{x} is
resampled with @var{n} points. The data in @var{x} is assumed to be
equispaced. If @var{x} is an array, then operate along each column of
the array seperately. If @var{dim} is specified, then interpolate
along the dimension @var{dim}.

@code{interpft} assumes that the interpolated function is periodic,
and so assumption are made about the end points of the inetrpolation.

@seealso{interp1}
@end deftypefn


@anchor{doc-interpn}
@deftypefn {Loadable Function} {@var{vi} =} interpn (@var{x1}, @var{x2}, @dots{}, @var{xn}, @var{v}, @var{y1}, @var{y2}, @dots{}, @var{yn})
Perform @var{n}-dimensional interpolation.  Each element of then
@var{n}-dimensional array @var{v} represents a value at a location
given by the parameters @var{x1}, @var{x2},...,@var{xn}. The parameters
@var{x1}, @var{x2}, @dots{}, @var{xn} are either @var{n}-dimensional
arrays of the same size as the array @var{v} in the "ndgrid" format
or vectors.  The parameters @var{y1}, @var{y2}, @dots{}, @var{yn} are
all @var{n}-dimensional arrays of the same size and represent the
points at which the array @var{vi} is interpolated.

This function only performs linear interpolation.
@seealso{interp1, interp2, ndgrid}
@end deftypefn


@anchor{doc-bicubic}
@deftypefn {Function File} {@var{zi}=} bicubic (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi})

Return a matrix @var{zi} corresponding to the bicubic
interpolations at @var{xi} and @var{yi} of the data supplied
as @var{x}, @var{y} and @var{z}. 

For further information please see bicubic.pdf available at
@url{http://wiki.woodpecker.org.cn/moin/Octave/Bicubic}
@seealso{interp2}
@end deftypefn


@anchor{doc-spline}
@deftypefn {Function File} {@var{pp} = } spline (@var{x}, @var{y})
@deftypefnx {Function File} {@var{yi} = } spline (@var{x}, @var{y}, @var{xi})

Returns the cubic spline interpolation of @var{y} at the point
@var{x}. Called with two arguments the piece-wise polynomial @var{pp}
that may later be used with @code{ppval} to evaluate the polynomial
at specific points.

The variable @var{x} must be a vector of length @var{n}, and @var{y}
can be either a vector or array. In the case where @var{y} is a
vector, it can have a length of either @var{n} or @code{@var{n} + 2}.
If the length of @var{y} is @var{n}, then the 'not-a-knot' end
condition is used. If the length of @var{y} is @code{@var{n} + 2},
then the first and last values of the vector @var{y} are the first
derivative of the cubic spline at the end-points.

If @var{y} is an array, then the size of @var{y} must have the form
@iftex
@tex
$$[s_1, s_2, \cdots, s_k, n]$$
@end tex
@end iftex
@ifinfo
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n}]}
@end ifinfo
or
@iftex
@tex
$$[s_1, s_2, \cdots, s_k, n + 2]$$.
@end tex
@end iftex
@ifinfo
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n} + 2]}.
@end ifinfo
The array is then reshaped internally to a matrix where to leading
dimension is given by 
@iftex
@tex
$$s_1 s_2 \cdots s_k$$
@end tex
@end iftex
@ifinfo
@code{@var{s1} * @var{s2} * @dots{} * @var{sk}}
@end ifinfo
and each row this matrix is then treated seperately. Note that this
is exactly the opposite treatment than @code{interp1} and is done
for compatiability.

Called with a third input argument, @code{spline} evaluates the 
piece-wise spline at the points @var{xi}. There is an equivalence
between @code{ppval (spline (@var{x}, @var{y}), @var{xi})} and
@code{spline (@var{x}, @var{y}, @var{xi})}.

@seealso{ppval, mkpp, unmkpp}
@end deftypefn


@anchor{doc-lookup}
@deftypefn {Function File} {@var{idx} =} lookup (@var{table}, @var{y})
Lookup values in a sorted table.  Usually used as a prelude to
interpolation.

If table is strictly increasing and @code{idx = lookup (table, y)}, then
@code{table(idx(i)) <= y(i) < table(idx(i+1))} for all @code{y(i)}
within the table.  If @code{y(i)} is before the table, then 
@code{idx(i)} is 0. If @code{y(i)} is after the table then
@code{idx(i)} is @code{table(n)}.

If the table is strictly decreasing, then the tests are reversed.
There are no guarantees for tables which are non-monotonic or are not
strictly monotonic.

To get an index value which lies within an interval of the table,
use:

@example
idx = lookup (table(2:length(table)-1), y) + 1
@end example

@noindent
This expression puts values before the table into the first
interval, and values after the table into the last interval.
@end deftypefn

