[Scipy-svn] r5248 - trunk/scipy/ndimage

scipy-svn@scip... scipy-svn@scip...
Sat Dec 13 22:20:53 CST 2008


Author: matthew.brett@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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)
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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)
 
-@moredoc(_mode_doc, _origin_doc)
+@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,))
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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)
 
-@moredoc(_mode_doc, _origin_doc)
+@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)
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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)
 
-@moredoc(_mode_doc, _origin_doc)
+@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)
 
-
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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')
 
-@moredoc(_mode_doc, _origin_doc)
+@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')
 
-@moredoc(_mode_doc, _origin_doc)
+@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')
 
-@moredoc(_mode_doc, _origin_doc)
+@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
 
-@moredoc(_mode_doc, _origin_doc)
+@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