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

scipy-svn@scip... scipy-svn@scip...
Tue Mar 8 20:02:13 CST 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.
-
--------
-    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 @@

-        """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)

```