[Scipy-svn] r5248 - trunk/scipy/ndimage
scipy-svn at scipy.org
scipy-svn at scipy.org
Sat Dec 13 23:20:53 EST 2008
Author: matthew.brett at gmail.com
Date: 2008-12-13 22:20:51 -0600 (Sat, 13 Dec 2008)
New Revision: 5248
Modified:
trunk/scipy/ndimage/filters.py
Log:
Added some more documentation for common optional parameters, changed default arguments from empty dictionary to None to prevent persistent changes in default
Modified: trunk/scipy/ndimage/filters.py
===================================================================
--- trunk/scipy/ndimage/filters.py 2008-12-14 02:59:20 UTC (rev 5247)
+++ trunk/scipy/ndimage/filters.py 2008-12-14 04:20:51 UTC (rev 5248)
@@ -34,23 +34,25 @@
import _nd_image
_mode_doc = \
-"""The mode parameter determines how the array borders are handled,
- where cval is the value when mode is equal to 'constant'. Other
+"""The ``mode`` parameter determines how the array borders are handled,
+ where ``cval`` is the value when mode is equal to 'constant'. Other
modes are 'nearest', 'mirror', 'reflect' and 'wrap'."""
-_origin_doc = """
+_origin_doc = \
+"""The ``origin`` parameter (optional) controls the placement of the filter."""
- The origin parameter controls the placement of the filter."""
+_output_doc = \
+"""The ``output`` parameter (optional) passes an array in which to store
+ the filter output."""
def moredoc(*args):
def decorate(f):
if f.__doc__ is not None:
- for a in args:
- f.__doc__ += a
+ f.__doc__ += '\n' + '\n'.join(args)
return f
return decorate
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def correlate1d(input, weights, axis = -1, output = None, mode = "reflect",
cval = 0.0, origin = 0):
"""Calculate a one-dimensional correlation along the given axis.
@@ -58,7 +60,6 @@
The lines of the array along the given axis are correlated with the
given weights. The weights parameter must be a one-dimensional sequence
of numbers.
-
"""
input = numpy.asarray(input)
if numpy.iscomplexobj(input):
@@ -78,7 +79,7 @@
origin)
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def convolve1d(input, weights, axis = -1, output = None, mode = "reflect",
cval = 0.0, origin = 0):
"""Calculate a one-dimensional convolution along the given axis.
@@ -86,7 +87,6 @@
The lines of the array along the given axis are convolved with the
given weights. The weights parameter must be a one-dimensional sequence
of numbers.
-
"""
weights = weights[::-1]
origin = -origin
@@ -104,7 +104,6 @@
kernel. An order of 1, 2, or 3 corresponds to convolution with the
first, second or third derivatives of a Gaussian. Higher order
derivatives are not implemented.
-
"""
sd = float(sigma)
# make the length of the filter equal to 4 times the standard
@@ -147,7 +146,7 @@
weights[lw - ii] = tmp
return correlate1d(input, weights, axis, output, mode, cval, 0)
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def gaussian_filter(input, sigma, order = 0, output = None,
mode = "reflect", cval = 0.0):
"""Multi-dimensional Gaussian filter.
@@ -167,7 +166,6 @@
types with a limited precision, the results may be imprecise
because intermediate results may be stored with insufficient
precision.
-
"""
input = numpy.asarray(input)
output, return_value = _ni_support._get_output(output, input)
@@ -185,10 +183,9 @@
output[...] = input[...]
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def prewitt(input, axis = -1, output = None, mode = "reflect", cval = 0.0):
"""Calculate a Prewitt filter.
-
"""
input = numpy.asarray(input)
axis = _ni_support._check_axis(axis, input.ndim)
@@ -199,10 +196,9 @@
correlate1d(output, [1, 1, 1], ii, output, mode, cval, 0,)
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def sobel(input, axis = -1, output = None, mode = "reflect", cval = 0.0):
"""Calculate a Sobel filter.
-
"""
input = numpy.asarray(input)
axis = _ni_support._check_axis(axis, input.ndim)
@@ -213,9 +209,11 @@
correlate1d(output, [1, 2, 1], ii, output, mode, cval, 0)
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def generic_laplace(input, derivative2, output = None, mode = "reflect",
- cval = 0.0, extra_arguments = (), extra_keywords = {}):
+ cval = 0.0,
+ extra_arguments = (),
+ extra_keywords = None):
"""Calculate a multidimensional laplace filter using the provided
second derivative function.
@@ -228,8 +226,9 @@
The extra_arguments and extra_keywords arguments can be used to pass
extra arguments and keywords that are passed to derivative2 at each
call.
-
"""
+ if extra_keywords is None:
+ extra_keywords = {}
input = numpy.asarray(input)
output, return_value = _ni_support._get_output(output, input)
axes = range(input.ndim)
@@ -244,17 +243,16 @@
output[...] = input[...]
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def laplace(input, output = None, mode = "reflect", cval = 0.0):
"""Calculate a multidimensional laplace filter using an estimation
for the second derivative based on differences.
-
"""
def derivative2(input, axis, output, mode, cval):
return correlate1d(input, [1, -2, 1], axis, output, mode, cval, 0)
return generic_laplace(input, derivative2, output, mode, cval)
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def gaussian_laplace(input, sigma, output = None, mode = "reflect",
cval = 0.0):
"""Calculate a multidimensional laplace filter using gaussian
@@ -263,7 +261,6 @@
The standard-deviations of the Gaussian filter are given for each
axis as a sequence, or as a single number, in which case it is
equal for all axes..
-
"""
input = numpy.asarray(input)
def derivative2(input, axis, output, mode, cval, sigma):
@@ -273,24 +270,30 @@
return generic_laplace(input, derivative2, output, mode, cval,
extra_arguments = (sigma,))
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def generic_gradient_magnitude(input, derivative, output = None,
mode = "reflect", cval = 0.0,
- extra_arguments = (), extra_keywords = {}):
- """Calculate a gradient magnitude using the provdide function for
+ extra_arguments = (), extra_keywords = None):
+ """Calculate a gradient magnitude using the provided function for
the gradient.
The derivative parameter must be a callable with the following
- signature:
+ signature::
- derivative(input, axis, output, mode, cval,
- *extra_arguments, **extra_keywords)
+ derivative(input, axis, output, mode, cval,
+ *extra_arguments, **extra_keywords)
+ ``derivative`` can assume that ``input`` and ``output`` are ndarrays.
+
+ Note that the output from ``derivative`` is modified inplace; be
+ careful to copy important inputs before returning them.
+
The extra_arguments and extra_keywords arguments can be used to pass
- extra arguments and keywords that are passed to derivative2 at each
+ extra arguments and keywords that are passed to ``derivative`` at each
call.
-
"""
+ if extra_keywords is None:
+ extra_keywords = {}
input = numpy.asarray(input)
output, return_value = _ni_support._get_output(output, input)
axes = range(input.ndim)
@@ -308,7 +311,7 @@
output[...] = input[...]
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def gaussian_gradient_magnitude(input, sigma, output = None,
mode = "reflect", cval = 0.0):
"""Calculate a multidimensional gradient magnitude using gaussian
@@ -317,7 +320,6 @@
The standard-deviations of the Gaussian filter are given for each
axis as a sequence, or as a single number, in which case it is
equal for all axes..
-
"""
input = numpy.asarray(input)
def derivative(input, axis, output, mode, cval, sigma):
@@ -353,36 +355,33 @@
_nd_image.correlate(input, weights, output, mode, cval, origins)
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def correlate(input, weights, output = None, mode = 'reflect', cval = 0.0,
origin = 0):
"""Multi-dimensional correlation.
The array is correlated with the given kernel.
-
"""
return _correlate_or_convolve(input, weights, output, mode, cval,
origin, False)
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def convolve(input, weights, output = None, mode = 'reflect', cval = 0.0,
origin = 0):
"""Multi-dimensional convolution.
The array is convolved with the given kernel.
-
"""
return _correlate_or_convolve(input, weights, output, mode, cval,
origin, True)
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def uniform_filter1d(input, size, axis = -1, output = None,
mode = "reflect", cval = 0.0, origin = 0):
"""Calculate a one-dimensional uniform filter along the given axis.
The lines of the array along the given axis are filtered with a
uniform filter of given size.
-
"""
input = numpy.asarray(input)
if numpy.iscomplexobj(input):
@@ -398,7 +397,7 @@
origin)
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def uniform_filter(input, size = 3, output = None, mode = "reflect",
cval = 0.0, origin = 0):
"""Multi-dimensional uniform filter.
@@ -412,7 +411,6 @@
in the same data type as the output. Therefore, for output types
with a limited precision, the results may be imprecise because
intermediate results may be stored with insufficient precision.
-
"""
input = numpy.asarray(input)
output, return_value = _ni_support._get_output(output, input)
@@ -430,14 +428,13 @@
output[...] = input[...]
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def minimum_filter1d(input, size, axis = -1, output = None,
mode = "reflect", cval = 0.0, origin = 0):
"""Calculate a one-dimensional minimum filter along the given axis.
The lines of the array along the given axis are filtered with a
minimum filter of given size.
-
"""
input = numpy.asarray(input)
if numpy.iscomplexobj(input):
@@ -453,14 +450,13 @@
origin, 1)
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def maximum_filter1d(input, size, axis = -1, output = None,
mode = "reflect", cval = 0.0, origin = 0):
"""Calculate a one-dimensional maximum filter along the given axis.
The lines of the array along the given axis are filtered with a
maximum filter of given size.
-
"""
input = numpy.asarray(input)
if numpy.iscomplexobj(input):
@@ -539,31 +535,29 @@
mode, cval, origins, minimum)
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def minimum_filter(input, size = None, footprint = None, output = None,
mode = "reflect", cval = 0.0, origin = 0):
"""Calculates a multi-dimensional minimum filter.
Either a size or a footprint with the filter must be
provided. An output array can optionally be provided.
-
"""
return _min_or_max_filter(input, size, footprint, None, output, mode,
cval, origin, 1)
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def maximum_filter(input, size = None, footprint = None, output = None,
mode = "reflect", cval = 0.0, origin = 0):
"""Calculates a multi-dimensional maximum filter.
Either a size or a footprint with the filter must be
provided. An output array can optionally be provided.
-
"""
return _min_or_max_filter(input, size, footprint, None, output, mode,
cval, origin, 0)
-
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def _rank_filter(input, rank, size = None, footprint = None, output = None,
mode = "reflect", cval = 0.0, origin = 0, operation = 'rank'):
input = numpy.asarray(input)
@@ -615,7 +609,7 @@
origins)
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def rank_filter(input, rank, size = None, footprint = None, output = None,
mode = "reflect", cval = 0.0, origin = 0):
"""Calculates a multi-dimensional rank filter.
@@ -624,24 +618,22 @@
indicates the larges element. Either a size or a footprint with
the filter must be provided. An output array can optionally be
provided.
-
"""
return _rank_filter(input, rank, size, footprint, output, mode, cval,
origin, 'rank')
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def median_filter(input, size = None, footprint = None, output = None,
mode = "reflect", cval = 0.0, origin = 0):
"""Calculates a multi-dimensional median filter.
Either a size or a footprint with the filter must be provided. An
output array can optionally be provided.
-
"""
return _rank_filter(input, 0, size, footprint, output, mode, cval,
origin, 'median')
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def percentile_filter(input, percentile, size = None, footprint = None,
output = None, mode = "reflect", cval = 0.0, origin = 0):
"""Calculates a multi-dimensional percentile filter.
@@ -650,12 +642,11 @@
-20 equals percentile = 80. Either a size or a footprint with the
filter must be provided. An output array can optionally be
provided.
-
"""
return _rank_filter(input, percentile, size, footprint, output, mode,
cval, origin, 'percentile')
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def generic_filter1d(input, function, filter_size, axis = -1,
output = None, mode = "reflect", cval = 0.0, origin = 0,
extra_arguments = (), extra_keywords = {}):
@@ -664,12 +655,11 @@
The function iterates over the lines of the array, calling the
given function at each line. The arguments of the line are the
input line, and the output line. The input and output lines are 1D
- double arrays. The input line is extended appropiately according
+ double arrays. The input line is extended appropriately according
to the filter size and origin. The output line must be modified
in-place with the result. The extra_arguments and extra_keywords
arguments can be used to pass extra arguments and keywords that
are passed to the function at each call.
-
"""
input = numpy.asarray(input)
if numpy.iscomplexobj(input):
@@ -686,10 +676,10 @@
mode, cval, origin, extra_arguments, extra_keywords)
return return_value
- at moredoc(_mode_doc, _origin_doc)
+ at moredoc(_mode_doc, _origin_doc, _output_doc)
def generic_filter(input, function, size = None, footprint = None,
output = None, mode = "reflect", cval = 0.0, origin = 0,
- extra_arguments = (), extra_keywords = {}):
+ extra_arguments = (), extra_keywords = None):
"""Calculates a multi-dimensional filter using the given function.
At each element the provided function is called. The input values
@@ -700,8 +690,9 @@
output array can optionally be provided. The extra_arguments and
extra_keywords arguments can be used to pass extra arguments and
keywords that are passed to the function at each call.
-
"""
+ if extra_keywords is None:
+ extra_keywords = {}
input = numpy.asarray(input)
if numpy.iscomplexobj(input):
raise TypeError, 'Complex type not supported'
More information about the Scipy-svn
mailing list