[Scipy-svn] r7183 - trunk/scipy/interpolate

scipy-svn at scipy.org scipy-svn at scipy.org
Tue Mar 8 21:02:13 EST 2011


Author: rgommers
Date: 2011-03-08 20:02:13 -0600 (Tue, 08 Mar 2011)
New Revision: 7183

Modified:
   trunk/scipy/interpolate/interpolate.py
   trunk/scipy/interpolate/polyint.py
Log:
DOC: merge edits to scipy.interpolate. Closes #1397.

Modified: trunk/scipy/interpolate/interpolate.py
===================================================================
--- trunk/scipy/interpolate/interpolate.py	2011-03-07 19:32:35 UTC (rev 7182)
+++ trunk/scipy/interpolate/interpolate.py	2011-03-09 02:02:13 UTC (rev 7183)
@@ -60,49 +60,82 @@
     interp2d(x, y, z, kind='linear', copy=True, bounds_error=False,
              fill_value=nan)
 
-    Interpolate over a 2D grid.
+    Interpolate over a 2-D grid.
 
+    `x`, `y` and `z` are arrays of values used to approximate some function
+    f: ``z = f(x, y)``. This class returns a function whose call method uses
+    spline interpolation to find the value of new points.
+
+    Methods
+    -------
+    __call__
+
     Parameters
     ----------
-    x, y : 1D arrays
+    x, y : 1-D ndarrays
         Arrays defining the data point coordinates.
 
         If the points lie on a regular grid, `x` can specify the column
         coordinates and `y` the row coordinates, for example::
 
-            x = [0,1,2];  y = [0,3]; z = [[1,2,3], [4,5,6]]
+          >>> x = [0,1,2];  y = [0,3]; z = [[1,2,3], [4,5,6]]
 
         Otherwise, x and y must specify the full coordinates for each point,
         for example::
 
-            x = [0,1,2,0,1,2];  y = [0,0,0,3,3,3]; z = [1,2,3,4,5,6]
+          >>> x = [0,1,2,0,1,2];  y = [0,0,0,3,3,3]; z = [1,2,3,4,5,6]
 
         If `x` and `y` are multi-dimensional, they are flattened before use.
 
-    z : 1D array
+    z : 1-D ndarray
         The values of the function to interpolate at the data points. If
-        z is a multi-dimensional array, it is flattened before use.
-    kind : {'linear', 'cubic', 'quintic'}
-        The kind of interpolation to use.
-    copy : bool
+        `z` is a multi-dimensional array, it is flattened before use.
+    kind : {'linear', 'cubic', 'quintic'}, optional
+        The kind of spline interpolation to use. Default is 'linear'.
+    copy : bool, optional
         If True, then data is copied, otherwise only a reference is held.
-    bounds_error : bool
+    bounds_error : bool, optional
         If True, when interpolated values are requested outside of the
         domain of the input data, an error is raised.
         If False, then `fill_value` is used.
-    fill_value : number
+    fill_value : number, optional
         If provided, the value to use for points outside of the
         interpolation domain. Defaults to NaN.
 
-    Raises
-    ------
-    ValueError when inputs are invalid.
-
     See Also
     --------
-    bisplrep, bisplev : spline interpolation based on FITPACK
+    bisplrep, bisplev
+        Spline interpolation based on FITPACK
     BivariateSpline : a more recent wrapper of the FITPACK routines
+    interp1d
 
+    Notes
+    -----
+    The minimum number of data points required along the interpolation
+    axis is ``(k+1)**2``, with k=1 for linear, k=3 for cubic and k=5 for
+    quintic interpolation.
+
+    The interpolator is constructed by `bisplrep`, with a smoothing factor
+    of 0. If more control over smoothing is needed, `bisplrep` should be
+    used directly.
+
+    Examples
+    --------
+    Construct a 2-D grid and interpolate on it:
+
+    >>> x = np.arange(-5.01, 5.01, 0.25)
+    >>> y = np.arange(-5.01, 5.01, 0.25)
+    >>> xx, yy = np.meshgrid(x, y)
+    >>> z = np.sin(xx**2+yy**2)
+    >>> f = sp.interpolate.interp2d(x, y, z, kind='cubic')
+
+    Now use the obtained interpolation function and plot the result:
+
+    >>> xnew = np.arange(-5.01, 5.01, 1e-2)
+    >>> ynew = np.arange(-5.01, 5.01, 1e-2)
+    >>> znew = f(xnew, ynew)
+    >>> plt.plot(x, z[:, 0], 'ro-', xnew, znew[:, 0], 'b-')
+
     """
 
     def __init__(self, x, y, z, kind='linear', copy=True, bounds_error=False,
@@ -162,12 +195,11 @@
     interp1d(x, y, kind='linear', axis=-1, copy=True, bounds_error=True,
              fill_value=np.nan)
 
-    Interpolate a 1D function.
+    Interpolate a 1-D function.
 
     `x` and `y` are arrays of values used to approximate some function f:
-        y = f(x)
-    This class returns a function whose call method uses linear interpolation
-    to find the value of new points.
+    ``y = f(x)``.  This class returns a function whose call method uses
+    interpolation to find the value of new points.
 
     Parameters
     ----------
@@ -202,17 +234,17 @@
     UnivariateSpline : A more recent wrapper of the FITPACK routines.
     splrep, splev
         Spline interpolation based on FITPACK.
+    interp2d
 
     Examples
     --------
     >>> import scipy.interpolate
-
     >>> x = np.arange(0, 10)
     >>> y = np.exp(-x/3.0)
     >>> f = sp.interpolate.interp1d(x, y)
 
     >>> xnew = np.arange(0,9, 0.1)
-    >>> ynew = f(xnew)
+    >>> ynew = f(xnew)   # use interpolation function returned by `interp1d`
     >>> plt.plot(x, y, 'o', xnew, ynew, '-')
 
     """

Modified: trunk/scipy/interpolate/polyint.py
===================================================================
--- trunk/scipy/interpolate/polyint.py	2011-03-07 19:32:35 UTC (rev 7182)
+++ trunk/scipy/interpolate/polyint.py	2011-03-09 02:02:13 UTC (rev 7183)
@@ -159,22 +159,25 @@
                 return p
 
     def derivatives(self,x,der=None):
-        """Evaluate many derivatives of the polynomial at the point x
+        """
+        Evaluate many derivatives of the polynomial at the point x
 
         Produce an array of all derivative values at the point x.
 
         Parameters
         ----------
-        x : scalar or array-like of length N
+        x : scalar or array_like of length N
             Point or points at which to evaluate the derivatives
+
         der : None or integer
             How many derivatives to extract; None for all potentially
             nonzero derivatives (that is a number equal to the number
             of points). This number includes the function value as 0th
             derivative.
+
         Returns
         -------
-        d : array
+        d : ndarray
             If the interpolator's values are R-dimensional then the
             returned array will be der by N by R. If x is a scalar,
             the middle dimension will be dropped; if R is 1 then the
@@ -188,6 +191,7 @@
         array([[1.0,1.0],
                [2.0,2.0],
                [3.0,3.0]])
+
         """
         if _isscalar(x):
             scalar = True
@@ -235,18 +239,21 @@
             else:
                 return cn[:der]
     def derivative(self,x,der):
-        """Evaluate one derivative of the polynomial at the point x
+        """
+        Evaluate one derivative of the polynomial at the point x
 
         Parameters
         ----------
-        x : scalar or array-like of length N
+        x : scalar or array_like of length N
             Point or points at which to evaluate the derivatives
+
         der : None or integer
             Which derivative to extract. This number includes the
             function value as 0th derivative.
+
         Returns
         -------
-        d : array
+        d : ndarray
             If the interpolator's values are R-dimensional then the
             returned array will be N by R. If x is a scalar,
             the middle dimension will be dropped; if R is 1 then the
@@ -256,11 +263,13 @@
         -----
         This is computed by evaluating all derivatives up to the desired
         one (using self.derivatives()) and then discarding the rest.
+
         """
         return self.derivatives(x,der=der+1)[der]
 
 def krogh_interpolate(xi,yi,x,der=0):
-    """Convenience function for polynomial interpolation.
+    """
+    Convenience function for polynomial interpolation.
 
     Constructs a polynomial that passes through a given set of points,
     optionally with specified derivatives at those points.
@@ -288,21 +297,22 @@
 
     Parameters
     ----------
-    xi : array-like, length N
+    xi : array_like, length N
         known x-coordinates
-    yi : array-like, N by R
+    yi : array_like, N by R
         known y-coordinates, interpreted as vectors of length R,
         or scalars if R=1
-    x : scalar or array-like of length N
+    x : scalar or array_like of length N
         Point or points at which to evaluate the derivatives
     der : integer or list
         How many derivatives to extract; None for all potentially
         nonzero derivatives (that is a number equal to the number
         of points), or a list of derivatives to extract. This number
         includes the function value as 0th derivative.
+
     Returns
     -------
-    d : array
+    d : ndarray
         If the interpolator's values are R-dimensional then the
         returned array will be the number of derivatives by N by R.
         If x is a scalar, the middle dimension will be dropped; if
@@ -313,6 +323,7 @@
     Construction of the interpolating polynomial is a relatively expensive
     process. If you want to evaluate it repeatedly consider using the class
     KroghInterpolator (which is what this function uses).
+
     """
     P = KroghInterpolator(xi, yi)
     if der==0:
@@ -428,7 +439,8 @@
         self.wi**=-1
 
     def set_yi(self, yi):
-        """Update the y values to be interpolated
+        """
+        Update the y values to be interpolated
 
         The barycentric interpolation algorithm requires the calculation
         of weights, but these depend only on the xi. The yi can be changed
@@ -436,10 +448,11 @@
 
         Parameters
         ----------
-        yi : array-like N by R
+        yi : array_like N by R
             The y coordinates of the points the polynomial should pass through;
             if R>1 the polynomial is vector-valued. If None the y values
             will be supplied later.
+
         """
         if yi is None:
             self.yi = None
@@ -461,20 +474,22 @@
 
 
     def add_xi(self, xi, yi=None):
-        """Add more x values to the set to be interpolated
+        """
+        Add more x values to the set to be interpolated
 
         The barycentric interpolation algorithm allows easy updating by
         adding more points for the polynomial to pass through.
 
         Parameters
         ----------
-        xi : array-like of length N1
+        xi : array_like of length N1
             The x coordinates of the points the polynomial should pass through
-        yi : array-like N1 by R or None
+        yi : array_like N1 by R or None
             The y coordinates of the points the polynomial should pass through;
             if R>1 the polynomial is vector-valued. If None the y values
             will be supplied later. The yi should be specified if and only if
             the interpolator has y values specified.
+
         """
         if yi is not None:
             if self.yi is None:
@@ -546,7 +561,8 @@
             else:
                 return p
 def barycentric_interpolate(xi, yi, x):
-    """Convenience function for polynomial interpolation
+    """
+    Convenience function for polynomial interpolation
 
     Constructs a polynomial that passes through a given set of points,
     then evaluates the polynomial. For reasons of numerical stability,
@@ -562,21 +578,24 @@
 
     Based on Berrut and Trefethen 2004, "Barycentric Lagrange Interpolation".
 
+
     Parameters
     ----------
-    xi : array-like of length N
+    xi : array_like of length N
         The x coordinates of the points the polynomial should pass through
-    yi : array-like N by R
+    yi : array_like N by R
         The y coordinates of the points the polynomial should pass through;
         if R>1 the polynomial is vector-valued.
-    x : scalar or array-like of length M
+    x : scalar or array_like of length M
 
+
     Returns
     -------
-    y : scalar or array-like of length R or length M or M by R
+    y : scalar or array_like of length R or length M or M by R
         The shape of y depends on the shape of x and whether the
         interpolator is vector-valued or scalar-valued.
 
+
     Notes
     -----
 
@@ -584,6 +603,7 @@
     If you want to call this many times with the same xi (but possibly
     varying yi or x) you should use the class BarycentricInterpolator.
     This is what this function uses internally.
+
     """
     return BarycentricInterpolator(xi, yi)(x)
 
@@ -679,16 +699,20 @@
         return KroghInterpolator(xi,yi)
 
     def append(self, xi, yi, order=None):
-        """Append a single point with derivatives to the PiecewisePolynomial
+        """
+        Append a single point with derivatives to the PiecewisePolynomial
 
         Parameters
         ----------
         xi : float
-        yi : array-like
+
+        yi : array_like
             yi is the list of derivatives known at xi
+
         order : integer or None
             a polynomial order, or instructions to use the highest
             possible order
+
         """
 
         yi = np.asarray(yi)
@@ -723,11 +747,12 @@
 
 
     def extend(self, xi, yi, orders=None):
-        """Extend the PiecewisePolynomial by a list of points
+        """
+        Extend the PiecewisePolynomial by a list of points
 
         Parameters
         ----------
-        xi : array-like of length N1
+        xi : array_like of length N1
             a sorted list of x-coordinates
         yi : list of lists of length N1
             yi[i] is the list of derivatives known at xi[i]
@@ -738,6 +763,7 @@
             +1 indicates increasing
             -1 indicates decreasing
             None indicates that it should be deduced from the first two xi
+
         """
 
         for i in xrange(len(xi)):
@@ -774,37 +800,43 @@
         return y
 
     def derivative(self, x, der):
-        """Evaluate a derivative of the piecewise polynomial
+        """
+        Evaluate a derivative of the piecewise polynomial
 
         Parameters
         ----------
-        x : scalar or array-like of length N
+        x : scalar or array_like of length N
+
         der : integer
             which single derivative to extract
 
         Returns
         -------
-        y : scalar or array-like of length R or length N or N by R
+        y : scalar or array_like of length R or length N or N by R
 
         Notes
         -----
         This currently computes (using self.derivatives()) all derivatives
         of the curve segment containing each x but returns only one.
+
         """
         return self.derivatives(x,der=der+1)[der]
 
     def derivatives(self, x, der):
-        """Evaluate a derivative of the piecewise polynomial
+        """
+        Evaluate a derivative of the piecewise polynomial
+
         Parameters
         ----------
-        x : scalar or array-like of length N
+        x : scalar or array_like of length N
+
         der : integer
             how many derivatives (including the function value as
             0th derivative) to extract
 
         Returns
         -------
-        y : array-like of shape der by R or der by N or der by N by R
+        y : array_like of shape der by R or der by N or der by N by R
 
         """
         if _isscalar(x):
@@ -825,23 +857,26 @@
 
 
 def piecewise_polynomial_interpolate(xi,yi,x,orders=None,der=0):
-    """Convenience function for piecewise polynomial interpolation
+    """
+    Convenience function for piecewise polynomial interpolation
 
     Parameters
     ----------
-    xi : array-like of length N
-        a sorted list of x-coordinates
-    yi : list of lists of length N
-        yi[i] is the list of derivatives known at xi[i]
-    x : scalar or array-like of length M
-    orders : list of integers, or integer
+    xi : array_like
+        A sorted list of x-coordinates, of length N.
+    yi : list of lists
+        yi[i] is the list of derivatives known at xi[i]. Of length N.
+    x : scalar or array_like
+        Of length M.
+    orders : int or list of ints
         a list of polynomial orders, or a single universal order
-    der : integer
-        which single derivative to extract
+    der : int
+        Which single derivative to extract.
 
     Returns
     -------
-    y : scalar or array-like of length R or length M or M by R
+    y : scalar or array_like
+        The result, of length R or length M or M by R,
 
     Notes
     -----
@@ -856,6 +891,7 @@
     Construction of these piecewise polynomials can be an expensive process;
     if you repeatedly evaluate the same polynomial, consider using the class
     PiecewisePolynomial (which is what this function does).
+
     """
 
     P = PiecewisePolynomial(xi, yi, orders)




More information about the Scipy-svn mailing list