[Scipy-svn] r6402 - trunk/scipy/interpolate
scipy-svn at scipy.org
scipy-svn at scipy.org
Mon May 24 09:09:52 EDT 2010
Author: rgommers
Date: 2010-05-24 08:09:52 -0500 (Mon, 24 May 2010)
New Revision: 6402
Modified:
trunk/scipy/interpolate/fitpack.py
trunk/scipy/interpolate/fitpack2.py
trunk/scipy/interpolate/polyint.py
Log:
DOC: merge wiki edits - interpolate module.
Modified: trunk/scipy/interpolate/fitpack.py
===================================================================
--- trunk/scipy/interpolate/fitpack.py 2010-05-24 13:09:36 UTC (rev 6401)
+++ trunk/scipy/interpolate/fitpack.py 2010-05-24 13:09:52 UTC (rev 6402)
@@ -432,43 +432,45 @@
#return l[0]
def splev(x,tck,der=0):
- """Evaulate a B-spline and its derivatives.
+ """
+ Evaluate a B-spline and its derivatives.
- Description:
+ Given the knots and coefficients of a B-spline representation, evaluate
+ the value of the smoothing polynomial and it's derivatives.
+ This is a wrapper around the FORTRAN routines splev and splder of FITPACK.
- Given the knots and coefficients of a B-spline representation, evaluate
- the value of the smoothing polynomial and it's derivatives.
- This is a wrapper around the FORTRAN routines splev and splder of FITPACK.
+ Parameters
+ ----------
+ x (u) -- a 1-D array of points at which to return the value of the
+ smoothed spline or its derivatives. If tck was returned from
+ splprep, then the parameter values, u should be given.
+ tck -- A sequence of length 3 returned by splrep or splprep containg the
+ knots, coefficients, and degree of the spline.
+ der -- The order of derivative of the spline to compute (must be less than
+ or equal to k).
- Inputs:
+ Returns
+ -------
+ y -- an array of values representing the spline function or curve.
+ If tck was returned from splrep, then this is a list of arrays
+ representing the curve in N-dimensional space.
- x (u) -- a 1-D array of points at which to return the value of the
- smoothed spline or its derivatives. If tck was returned from
- splprep, then the parameter values, u should be given.
- tck -- A sequence of length 3 returned by splrep or splprep containg the
- knots, coefficients, and degree of the spline.
- der -- The order of derivative of the spline to compute (must be less than
- or equal to k).
+ See Also
+ --------
+ splprep, splrep, sproot, spalde, splint : evaluation, roots, integral
+ bisplrep, bisplev : bivariate splines
+ UnivariateSpline, BivariateSpline :
+ An alternative wrapping of the FITPACK functions.
- Outputs: (y, )
+ References
+ ----------
+ .. [1] C. de Boor, "On calculating with b-splines", J. Approximation
+ Theory, 6, p.50-62, 1972.
+ .. [2] M.G. Cox, "The numerical evaluation of b-splines", J. Inst. Maths
+ Applics, 10, p.134-149, 1972.
+ .. [3] P. Dierckx, "Curve and surface fitting with splines", Monographs
+ on Numerical Analysis, Oxford University Press, 1993.
- y -- an array of values representing the spline function or curve.
- If tck was returned from splrep, then this is a list of arrays
- representing the curve in N-dimensional space.
-
- See also:
- splprep, splrep, sproot, spalde, splint - evaluation, roots, integral
- bisplrep, bisplev - bivariate splines
- UnivariateSpline, BivariateSpline - an alternative wrapping
- of the FITPACK functions
-
- Notes:
- de Boor C : On calculating with b-splines, J. Approximation Theory
- 6 (1972) 50-62.
- Cox M.G. : The numerical evaluation of b-splines, J. Inst. Maths
- Applics 10 (1972) 134-149.
- Dierckx P. : Curve and surface fitting with splines, Monographs on
- Numerical Analysis, Oxford University Press, 1993.
"""
t,c,k=tck
try:
@@ -489,37 +491,39 @@
return y[0]
def splint(a,b,tck,full_output=0):
- """Evaluate the definite integral of a B-spline.
+ """
+ Evaluate the definite integral of a B-spline.
- Description:
+ Given the knots and coefficients of a B-spline, evaluate the definite
+ integral of the smoothing polynomial between two given points.
- Given the knots and coefficients of a B-spline, evaluate the definite
- integral of the smoothing polynomial between two given points.
+ Parameters
+ ----------
+ a, b -- The end-points of the integration interval.
+ tck -- A length 3 sequence describing the given spline (See splev).
+ full_output -- Non-zero to return optional output.
- Inputs:
+ Returns
+ -------
+ integral -- The resulting integral.
- a, b -- The end-points of the integration interval.
- tck -- A length 3 sequence describing the given spline (See splev).
- full_output -- Non-zero to return optional output.
+ wrk -- An array containing the integrals of the
+ normalized B-splines defined on the set of knots.
- Outputs: (integral, {wrk})
+ See Also
+ --------
+ splprep, splrep, sproot, spalde, splev : evaluation, roots, integral
+ bisplrep, bisplev : bivariate splines
+ UnivariateSpline, BivariateSpline :
+ An alternative wrapping of the FITPACK functions.
- integral -- The resulting integral.
- wrk -- An array containing the integrals of the normalized B-splines defined
- on the set of knots.
+ References
+ ----------
+ .. [1] P.W. Gaffney, The calculation of indefinite integrals of b-splines",
+ J. Inst. Maths Applics, 17, p.37-41, 1976.
+ .. [2] P. Dierckx, "Curve and surface fitting with splines", Monographs
+ on Numerical Analysis, Oxford University Press, 1993.
-
- See also:
- splprep, splrep, sproot, spalde, splev - evaluation, roots, integral
- bisplrep, bisplev - bivariate splines
- UnivariateSpline, BivariateSpline - an alternative wrapping
- of the FITPACK functions
-
- Notes:
- Gaffney P.W. : The calculation of indefinite integrals of b-splines
- J. Inst. Maths Applics 17 (1976) 37-41.
- Dierckx P. : Curve and surface fitting with splines, Monographs on
- Numerical Analysis, Oxford University Press, 1993.
"""
t,c,k=tck
try:
@@ -535,30 +539,45 @@
else: return aint
def sproot(tck,mest=10):
- """Find the roots of a cubic B-spline.
+ """
+ Find the roots of a cubic B-spline.
- Description:
+ Given the knots (>=8) and coefficients of a cubic B-spline return the
+ roots of the spline.
- Given the knots (>=8) and coefficients of a cubic B-spline return the
- roots of the spline.
+ Parameters
+ ----------
- Inputs:
+ tck -- A length 3 sequence describing the given spline (See splev).
+ The number of knots must be >= 8. The knots must be a montonically
+ increasing sequence.
- tck -- A length 3 sequence describing the given spline (See splev).
- The number of knots must be >= 8. The knots must be a montonically
- increasing sequence.
- mest -- An estimate of the number of zeros (Default is 10).
+ mest -- An estimate of the number of zeros (Default is 10)
- Outputs: (zeros, )
- zeros -- An array giving the roots of the spline.
+ Returns
+ -------
- See also:
- splprep, splrep, splint, spalde, splev - evaluation, roots, integral
- bisplrep, bisplev - bivariate splines
- UnivariateSpline, BivariateSpline - an alternative wrapping
- of the FITPACK functions
+ zeros -- An array giving the roots of the spline.
+ See also
+ --------
+ splprep, splrep, splint, spalde, splev :
+ evaluation, roots, integral
+ bisplrep, bisplev :
+ bivariate splines
+ UnivariateSpline, BivariateSpline :
+ An alternative wrapping of the FITPACK functions.
+
+ References
+ ----------
+ .. [1] C. de Boor, "On calculating with b-splines", J. Approximation
+ Theory, 6, p.50-62, 1972.
+ .. [2] M.G. Cox, "The numerical evaluation of b-splines", J. Inst. Maths
+ Applics, 10, p.134-149, 1972.
+ .. [3] P. Dierckx, "Curve and surface fitting with splines", Monographs
+ on Numerical Analysis, Oxford University Press, 1993.
+
"""
t,c,k=tck
if k==4: t=t[1:-1]
@@ -868,40 +887,49 @@
return dfitpack.dblint(tx,ty,c,kx,ky,xb,xe,yb,ye)
def insert(x,tck,m=1,per=0):
- """Insert knots into a B-spline.
+ """
+ Insert knots into a B-spline.
- Description:
+ Given the knots and coefficients of a B-spline representation, create a
+ new B-spline with a knot inserted m times at point x.
+ This is a wrapper around the FORTRAN routine insert of FITPACK.
- Given the knots and coefficients of a B-spline representation, create a
- new B-spline with a knot inserted m times at point x.
- This is a wrapper around the FORTRAN routine insert of FITPACK.
+ Parameters
+ ----------
- Inputs:
+ x (u) -- A 1-D point at which to insert a new knot(s). If tck was returned
+ from splprep, then the parameter values, u should be given.
+ tck -- A sequence of length 3 returned by splrep or splprep containg the
+ knots, coefficients, and degree of the spline.
- x (u) -- A 1-D point at which to insert a new knot(s). If tck was returned
- from splprep, then the parameter values, u should be given.
- tck -- A sequence of length 3 returned by splrep or splprep containg the
- knots, coefficients, and degree of the spline.
- m -- The number of times to insert the given knot (its multiplicity).
- per -- If non-zero, input spline is considered periodic.
+ m -- The number of times to insert the given knot (its multiplicity).
- Outputs: tck
+ per -- If non-zero, input spline is considered periodic.
- tck -- (t,c,k) a tuple containing the vector of knots, the B-spline
+ Returns
+ -------
+
+ tck -- (t,c,k) a tuple containing the vector of knots, the B-spline
coefficients, and the degree of the new spline.
- Requirements:
- t(k+1) <= x <= t(n-k), where k is the degree of the spline.
- In case of a periodic spline (per != 0) there must be
- either at least k interior knots t(j) satisfying t(k+1)<t(j)<=x
- or at least k interior knots t(j) satisfying x<=t(j)<t(n-k).
- Notes:
- Based on algorithms from:
- Boehm W : Inserting new knots into b-spline curves. Computer Aided
- Design 12 (1980) 199-201.
- Dierckx P. : Curve and surface fitting with splines, Monographs on
- Numerical Analysis, Oxford University Press, 1993.
+ t(k+1) <= x <= t(n-k), where k is the degree of the spline.
+ In case of a periodic spline (per != 0) there must be
+ either at least k interior knots t(j) satisfying t(k+1)<t(j)<=x
+ or at least k interior knots t(j) satisfying x<=t(j)<t(n-k).
+
+
+ Notes
+ -----
+ Based on algorithms from [1]_ and [2]_.
+
+ References
+ ----------
+ .. [1] W. Boehm, "Inserting new knots into b-spline curves.",
+ Computer Aided Design, 12, p.199-201, 1980.
+ .. [2] P. Dierckx, "Curve and surface fitting with splines, Monographs on
+ Numerical Analysis", Oxford University Press, 1993.
+
"""
t,c,k=tck
try:
Modified: trunk/scipy/interpolate/fitpack2.py
===================================================================
--- trunk/scipy/interpolate/fitpack2.py 2010-05-24 13:09:36 UTC (rev 6401)
+++ trunk/scipy/interpolate/fitpack2.py 2010-05-24 13:09:52 UTC (rev 6402)
@@ -52,30 +52,61 @@
}
class UnivariateSpline(object):
- """Univariate spline s(x) of degree k on the interval
- [xb,xe] calculated from a given set of data points
- (x,y).
+ """
+ One-dimensional smoothing spline fit to a given set of data points.
- Can include least-squares fitting.
+ Fits a spline y=s(x) of degree `k` to the provided `x`,`y` data. `s`
+ specifies the number of knots by specifying a smoothing condition.
+ Parameters
+ ----------
+ x : sequence
+ input dimension of data points -- must be increasing
+ y : sequence
+ input dimension of data points
+ w : sequence or None, optional
+ weights for spline fitting. Must be positive. If None (default),
+ weights are all equal.
+ bbox : sequence or None, optional
+ 2-sequence specifying the boundary of the approximation interval. If
+ None (default), bbox=[x[0],x[-1]].
+ k : int, optional
+ Degree of the smoothing spline. Must be <= 5.
+ s : float or None, optional
+ Positive smoothing factor used to choose the number of knots. Number
+ of knots will be increased until the smoothing condition is satisfied:
+
+ sum((w[i]*(y[i]-s(x[i])))**2,axis=0) <= s
+
+ If None (default), s=len(w) which should be a good value if 1/w[i] is
+ an estimate of the standard deviation of y[i]. If 0, spline will
+ interpolate through all data points.
+
+
See Also
--------
- splrep, splev, sproot, spint, spalde
- An older wrapping of FITPACK
- BivariateSpline
- A similar class for bivariate spline interpolation
+ InterpolatedUnivariateSpline : Subclass with smoothing forced to 0
+ LSQUnivariateSpline : Subclass in which knots are user-selected instead of
+ being set by smoothing condition
+ splrep : An older, non object-oriented wrapping of FITPACK
+ splev, sproot, splint, spalde
+ BivariateSpline : A similar class for two-dimensional spline interpolation
- Methods
- -------
- __call__
- get_knots
- get_coeffs
- get_residual
- integral
- derivatives
- roots
- set_smoothing_factor
+
+ Examples
+ --------
+ >>> from numpy import linspace,exp
+ >>> from numpy.random import randn
+ >>> from scipy.interpolate import UnivariateSpline
+ >>> x = linspace(-3,3,100)
+ >>> y = exp(-x**2) + randn(100)/10
+ >>> s = UnivariateSpline(x,y,s=1)
+ >>> xs = linspace(-3,3,1000)
+ >>> ys = s(xs)
+
+ xs,ys is now a smoothed, super-sampled version of the noisy gaussian x,y
+
"""
def __init__(self, x, y, w=None, bbox = [None]*2, k=3, s=None):
@@ -231,9 +262,53 @@
'finding roots unsupported for non-cubic splines'
class InterpolatedUnivariateSpline(UnivariateSpline):
- """ Interpolated univariate spline approximation. Identical to
- UnivariateSpline with less error checking.
+ """
+ One-dimensional interpolating spline for a given set of data points.
+ Fits a spline y=s(x) of degree `k` to the provided `x`,`y` data. Spline
+ function passes through all provided points. Equivalent to
+ `UnivariateSpline` with s=0.
+
+ Parameters
+ ----------
+ x : sequence
+ input dimension of data points -- must be increasing
+ y : sequence
+ input dimension of data points
+ w : sequence or None, optional
+ weights for spline fitting. Must be positive. If None (default),
+ weights are all equal.
+ bbox : sequence or None, optional
+ 2-sequence specifying the boundary of the approximation interval. If
+ None (default), bbox=[x[0],x[-1]].
+ k : int, optional
+ Degree of the smoothing spline. Must be <= 5.
+
+
+ See Also
+ --------
+ UnivariateSpline : Superclass -- allows knots to be selected by a
+ smoothing condition
+ LSQUnivariateSpline : spline for which knots are user-selected
+ splrep : An older, non object-oriented wrapping of FITPACK
+ splev, sproot, splint, spalde
+ BivariateSpline : A similar class for two-dimensional spline interpolation
+
+
+
+ Examples
+ --------
+ >>> from numpy import linspace,exp
+ >>> from numpy.random import randn
+ >>> from scipy.interpolate import UnivariateSpline
+ >>> x = linspace(-3,3,100)
+ >>> y = exp(-x**2) + randn(100)/10
+ >>> s = UnivariateSpline(x,y,s=1)
+ >>> xs = linspace(-3,3,1000)
+ >>> ys = s(xs)
+
+ xs,ys is now a smoothed, super-sampled version of the noisy gaussian x,y
+
"""
def __init__(self, x, y, w=None, bbox = [None]*2, k=3):
@@ -255,10 +330,62 @@
self._reset_class()
class LSQUnivariateSpline(UnivariateSpline):
- """ Weighted least-squares univariate spline
- approximation. Appears to be identical to UnivariateSpline with
- more error checking.
+ """
+ One-dimensional spline with explicit internal knots.
+ Fits a spline y=s(x) of degree `k` to the provided `x`,`y` data. `t`
+ specifies the internal knots of the spline
+
+ Parameters
+ ----------
+ x : sequence
+ input dimension of data points -- must be increasing
+ y : sequence
+ input dimension of data points
+ t: sequence
+ interior knots of the spline. Must be in ascending order
+ and bbox[0]<t[0]<...<t[-1]<bbox[-1]
+ w : sequence or None, optional
+ weights for spline fitting. Must be positive. If None (default),
+ weights are all equal.
+ bbox : sequence or None, optional
+ 2-sequence specifying the boundary of the approximation interval. If
+ None (default), bbox=[x[0],x[-1]].
+ k : int, optional
+ Degree of the smoothing spline. Must be <= 5.
+
+ Raises
+ ------
+
+ ValueError
+ If the interior knots do not satisfy the Schoenberg-Whitney conditions
+
+ See Also
+ --------
+ UnivariateSpline : Superclass -- knots are specified by setting a
+ smoothing condition
+ InterpolatedUnivariateSpline : spline passing through all points
+ splrep : An older, non object-oriented wrapping of FITPACK
+ splev, sproot, splint, spalde
+ BivariateSpline : A similar class for two-dimensional spline interpolation
+
+
+
+ Examples
+ --------
+ >>> from numpy import linspace,exp
+ >>> from numpy.random import randn
+ >>> from scipy.interpolate import LSQUnivariateSpline
+ >>> x = linspace(-3,3,100)
+ >>> y = exp(-x**2) + randn(100)/10
+ >>> t = [-1,0,1]
+ >>> s = LSQUnivariateSpline(x,y,t)
+ >>> xs = linspace(-3,3,1000)
+ >>> ys = s(xs)
+
+ xs,ys is now a smoothed, super-sampled version of the noisy gaussian x,y
+ with knots [-3,-1,0,1,3]
+
"""
def __init__(self, x, y, t, w=None, bbox = [None]*2, k=3):
Modified: trunk/scipy/interpolate/polyint.py
===================================================================
--- trunk/scipy/interpolate/polyint.py 2010-05-24 13:09:36 UTC (rev 6401)
+++ trunk/scipy/interpolate/polyint.py 2010-05-24 13:09:52 UTC (rev 6402)
@@ -4,7 +4,8 @@
__all__ = ["KroghInterpolator", "krogh_interpolate", "BarycentricInterpolator", "barycentric_interpolate", "PiecewisePolynomial", "piecewise_polynomial_interpolate","approximate_taylor_polynomial", "pchip"]
class KroghInterpolator(object):
- """The interpolating polynomial for a set of points
+ """
+ The interpolating polynomial for a set of points
Constructs a polynomial that passes through a given set of points,
optionally with specified derivatives at those points.
@@ -22,8 +23,22 @@
x values, degrees higher than about thirty cause problems with
numerical instability in this code.
- Based on Krogh 1970, "Efficient Algorithms for Polynomial Interpolation
- and Numerical Differentiation"
+ Based on [1]_.
+
+ Parameters
+ ----------
+ xi : array-like, length N
+ Known x-coordinates
+ yi : array-like, N by R
+ Known y-coordinates, interpreted as vectors of length R,
+ or scalars if R=1. When an xi occurs two or more times in
+ a row, the corresponding yi's represent derivative values.
+
+ References
+ ----------
+ .. [1] Krogh, "Efficient Algorithms for Polynomial Interpolation
+ and Numerical Differentiation", 1970.
+
"""
def __init__(self, xi, yi):
"""Construct an interpolator passing through the specified points
@@ -311,9 +326,9 @@
def approximate_taylor_polynomial(f,x,degree,scale,order=None):
- """Estimate the Taylor polynomial of f at x by polynomial fitting
+ """
+ Estimate the Taylor polynomial of f at x by polynomial fitting.
- A polynomial
Parameters
----------
f : callable
@@ -321,32 +336,33 @@
a vector of x values.
x : scalar
The point at which the polynomial is to be evaluated.
- degree : integer
+ degree : int
The degree of the Taylor polynomial
scale : scalar
The width of the interval to use to evaluate the Taylor polynomial.
Function values spread over a range this wide are used to fit the
polynomial. Must be chosen carefully.
- order : integer or None
+ order : int or None
The order of the polynomial to be used in the fitting; f will be
- evaluated order+1 times. If None, use degree.
+ evaluated ``order+1`` times. If None, use `degree`.
Returns
-------
- p : poly1d
- the Taylor polynomial (translated to the origin, so that
+ p : poly1d instance
+ The Taylor polynomial (translated to the origin, so that
for example p(0)=f(x)).
Notes
-----
- The appropriate choice of "scale" is a tradeoff - too large and the
+ The appropriate choice of "scale" is a trade-off; too large and the
function differs from its Taylor polynomial too much to get a good
- answer, too small and roundoff errors overwhelm the higher-order terms.
+ answer, too small and round-off errors overwhelm the higher-order terms.
The algorithm used becomes numerically unstable around order 30 even
under ideal circumstances.
Choosing order somewhat larger than degree may improve the higher-order
terms.
+
"""
if order is None:
order=degree
More information about the Scipy-svn
mailing list