.. _interp:

Data Interpolation
========================

.. include:: ../replace.txt

.. index:: fillmissing, interp1, NaN

|M| has two functions that will interpolate between known data samples to
estimate unknown sample points. The difference between the two functions
relates just to the purpose for calling them.  The `fillmissing
<https://www.mathworks.com/help/matlab/ref/fillmissing.html>`_ function is
used when values that should be in the data are missing -- often replaced
with the NaN symbol. The `interp1
<https://www.mathworks.com/help/matlab/ref/interp1.html>`_ function is used
when you wish to add data points not contained in the data. |M| has similar
functions for some of the data interpolation algorithms that can be invoked by
``fillmissing`` and ``interp1``. These include ``pchip``, ``spline``, and 
``makima``.

Several different interpolation algorithms are available.  The default is
``'linear'``, which is good for slowly changing data or when there are a lot of
sample points.  The methods ``'pchip'``, ``'makima'``, and ``'spline'`` yield
very good results.  The 'spline' method requires the most computation because
it uses a matrix computation for each point to determine polynomial
coefficients that not only match that data, but maintain constant first and
second order derivatives at each data point added, which makes the curves
between data points smooth. However, the 'spline' method may overshoot data
fluctuation causing and an oscillation. The 'pchip' and 'makima' algorithms
give similar results, they maintain consistent first order derivatives at each
point, but not second order derivatives.  They avoid overshoots and can
accurately connect the flat regions.  Another advantage of the 'pchip' and
'makima' algorithms is that the known data points are either monotonically
increasing or decreasing, so will the interpolated data points. Because of
oscillations, may not always maintain the monotonicity of the data. In the
comparison plots below, the 'pchip' interpolation is shown, but the 'makima'
interpolation is not shown because 'pchip' gives similar results with slightly
less computation.

::

    f = @(x) 1 + x.^2 - x.^3 + 20*sin(x);
    x1 = (-3:1.5:3)';  % Limited data points
    y1 = f(x1);
    x2 = (-3:0.5:3)';  % More data points
    subplot(2,2,1) 
    plot(x1,y1,'o',x2,interp1(x1,y1,x2,'nearest'),'*-'), title('nearest')
    subplot(2,2,2)
    plot(x1,y1,'o',x2,interp1(x1,y1,x2,'linear'),'*-'), title('Linear')
    subplot(2,2,3) 
    plot(x1,y1,'o',x2,interp1(x1,y1,x2,'pchip'),'*-'), title('pchip')
    subplot(2,2,4) 
    plot(x1,y1,'o',x2,interp1(x1,y1,x2,'spline'),'*-'), title('spline')

.. _fig-interpPlot:

.. figure:: interpPlot.png
    :align: center

    The ``interp1`` and ``fillmissing`` functions can use different data
    interpolation algorithms to suite the application needs.

The following example illustrates the difference between 'pchip' and 'spline'
interpolation results. The 'pchip' result may be less smooth, but the
monotonicity of the data is preserved.

::

    x = -3:3;
    y = [-1 -1 -1 0 1 1 1];
    t = -3:.01:3;
    hold on
    plot(x, y, 'o')
    plot(t, interp1(x, y, t, 'pchip'), 'g')
    plot(t, interp1(x, y, t, 'spline'), '-.r')
    legend('data','pchip','spline', 'Location', 'NorthWest')
    hold off

.. _fig-interp1:

.. figure:: interp1.png
    :align: center

    Comparison of 'pchip' and 'spline' data inerpolation.

.. raw:: latex

    \clearpage