[Scipy-svn] r6662 - in trunk/doc/source: . tutorial

Tue Aug 31 18:00:43 EDT 2010

Author: ptvirtan
Date: 2010-08-31 17:00:43 -0500 (Tue, 31 Aug 2010)
New Revision: 6662

Modified:
   trunk/doc/source/interpolate.rst
   trunk/doc/source/tutorial/interpolate.rst
Log:
DOC: add documentation for griddata and the other N-dimensional interpolation utilities

Modified: trunk/doc/source/interpolate.rst
===================================================================

--- trunk/doc/source/interpolate.rst	2010-08-31 22:00:18 UTC (rev 6661)
+++ trunk/doc/source/interpolate.rst	2010-08-31 22:00:43 UTC (rev 6662)
@@ -22,13 +22,25 @@
 Multivariate interpolation
 ==========================
 
+Unstructured data:
+
 .. autosummary::
    :toctree: generated/
 
-   interp2d
+   griddata
+   LinearNDInterpolator
+   NearestNDInterpolator
+   CloughTocher2DInterpolator
    Rbf
 
+Data given on a regular grid:
 
+.. autosummary::
+   :toctree: generated/
+
+   interp2d
+
+
 1-D Splines
 ===========
 

Modified: trunk/doc/source/tutorial/interpolate.rst
===================================================================
--- trunk/doc/source/tutorial/interpolate.rst	2010-08-31 22:00:18 UTC (rev 6661)
+++ trunk/doc/source/tutorial/interpolate.rst	2010-08-31 22:00:43 UTC (rev 6662)
@@ -1,3 +1,4 @@
+========================================
 Interpolation (:mod:`scipy.interpolate`)
 ========================================
 
@@ -3,19 +4,31 @@
 .. sectionauthor:: Travis E. Oliphant
 
+.. sectionauthor:: Pauli Virtanen
+
 .. currentmodule:: scipy.interpolate
 
 .. contents::
 
-There are two general interpolation facilities available in SciPy. The
-first facility is an interpolation class which performs linear
-1-dimensional interpolation. The second facility is based on the
-FORTRAN library FITPACK and provides functions for 1- and
-2-dimensional (smoothed) cubic-spline interpolation. There are both
-procedural and object-oriented interfaces for the FITPACK library.
+There are several general interpolation facilities available in SciPy,
+for data in 1, 2, and higher dimensions:
 
+- A class representing an interpolant (:class:`interp1d`) in 1-D,
+  offering several interpolation methods.
 
-Linear 1-d interpolation (:class:`interp1d`)
---------------------------------------------
+- Convenience function :func:`griddata` offering a simple interface to
+  interpolation in N dimensions (N = 1, 2, 3, 4, ...).
+  Object-oriented interface for the underlying routines is also
+  available.
 
+- Functions for 1- and 2-dimensional (smoothed) cubic-spline
+  interpolation, based on the FORTRAN library FITPACK. There are both
+  procedural and object-oriented interfaces for the FITPACK library.
+
+- Interpolation using Radial Basis Functions.
+
+
+1-D interpolation (:class:`interp1d`)
+=====================================
+
 The interp1d class in scipy.interpolate is a convenient method to
 create a function based on fixed data points which can be evaluated
@@ -27,25 +40,83 @@
 interpolates between known data values to obtain unknown values (it
 also has a docstring for help). Behavior at the boundary can be
 specified at instantiation time. The following example demonstrates
-it's use.
+its use, for linear and cubic spline interpolation:
 
 .. plot::
 
-   >>> import numpy as np
-   >>> from scipy import interpolate
+   >>> from scipy.interpolate import interp1d
 
-   >>> x = np.arange(0,10)
+   >>> x = np.linspace(0, 10, 10)
    >>> y = np.exp(-x/3.0)
-   >>> f = interpolate.interp1d(x, y)
+   >>> f = interp1d(x, y)
+   >>> f2 = interp1d(x, y, kind='cubic')
 
-   >>> xnew = np.arange(0,9,0.1)
+   >>> xnew = np.linspace(0, 10, 40)
    >>> import matplotlib.pyplot as plt
-   >>> plt.plot(x,y,'o',xnew,f(xnew),'-')
+   >>> plt.plot(x,y,'o',xnew,f(xnew),'-', xnew, f2(xnew),'--')
+   >>> plt.legend(['data', 'linear', 'cubic'], loc='best')
+   >>> plt.show()
 
 ..   :caption: One-dimensional interpolation using the
 ..             class :obj:`interpolate.interp1d`
 
 
+Multivariate data interpolation (:func:`griddata`)
+==================================================
+
+Suppose you have multidimensional data, for instance for an underlying
+function *f(x, y)* you only know the values at points *(x[i], y[i])*
+that do not form a regular grid.
+
+.. plot::
+
+    Suppose we want to interpolate the 2-D function
+
+    >>> def func(x, y):
+    >>>     return x*(1-x)*np.cos(4*np.pi*x) * np.sin(4*np.pi*y**2)**2
+
+    on a grid in [0, 1]x[0, 1]
+
+    >>> grid_x, grid_y = np.mgrid[0:1:100j, 0:1:200j]
+
+    but we only know its values at 1000 data points:
+
+    >>> points = np.random.rand(1000, 2)
+    >>> values = func(points[:,0], points[:,1])
+
+    This can be done with `griddata` -- below we try out all of the
+    interpolation methods:
+
+    >>> from scipy.interpolate import griddata
+    >>> grid_z0 = griddata(points, values, (grid_x, grid_y), method='nearest')
+    >>> grid_z1 = griddata(points, values, (grid_x, grid_y), method='linear')
+    >>> grid_z2 = griddata(points, values, (grid_x, grid_y), method='cubic')
+
+    One can see that the exact result is reproduced by all of the
+    methods to some degree, but for this smooth function the piecewise
+    cubic interpolant gives the best results:
+
+    >>> import matplotlib.pyplot as plt
+    >>> plt.subplot(221)
+    >>> plt.imshow(func(grid_x, grid_y).T, extent=(0,1,0,1), origin='lower')
+    >>> plt.plot(points[:,0], points[:,1], 'k.', ms=1)
+    >>> plt.title('Original')
+    >>> plt.subplot(222)
+    >>> plt.imshow(grid_z0.T, extent=(0,1,0,1), origin='lower')
+    >>> plt.title('Nearest')
+    >>> plt.subplot(223)
+    >>> plt.imshow(grid_z1.T, extent=(0,1,0,1), origin='lower')
+    >>> plt.title('Linear')
+    >>> plt.subplot(224)
+    >>> plt.imshow(grid_z2.T, extent=(0,1,0,1), origin='lower')
+    >>> plt.title('Cubic')
+    >>> plt.gcf().set_size_inches(6, 6)
+    >>> plt.show()
+
+
+Spline interpolation
+====================
+
 Spline interpolation in 1-d: Procedural (interpolate.splXXX)
 ------------------------------------------------------------
 
@@ -220,8 +291,8 @@
 
    LSQUnivarateSpline with non-uniform knots
 
-   >>> t = [np.pi/2-.1,np.pi/2-.1,3*np.pi/2-.1,3*np.pi/2+.1]
-   >>> s = interpolate.LSQUnivariateSpline(x,y,t)
+   >>> t = [np.pi/2-.1,np.pi/2+.1,3*np.pi/2-.1,3*np.pi/2+.1]
+   >>> s = interpolate.LSQUnivariateSpline(x,y,t,k=2)
    >>> ynew = s(xnew)
 
    >>> plt.figure()
@@ -232,7 +303,6 @@
    >>> plt.show()
 
 
-
 Two-dimensional spline representation: Procedural (:func:`bisplrep`)
 --------------------------------------------------------------------
 
@@ -319,14 +389,14 @@
 
 
 Using radial basis functions for smoothing/interpolation
----------------------------------------------------------
+========================================================
 
 Radial basis functions can be used for smoothing/interpolating scattered
 data in n-dimensions, but should be used with caution for extrapolation
 outside of the observed data range.
 
 1-d Example
-^^^^^^^^^^^
+-----------
 
 This example compares the usage of the Rbf and UnivariateSpline classes
 from the scipy.interpolate module.
@@ -366,7 +436,7 @@
 ..   :caption: Example of one-dimensional RBF interpolation.
 
 2-d Example
-^^^^^^^^^^^
+-----------
 
 This example shows how to interpolate scattered 2d data.
 


