Merge pull request #116 from aaren/dwt_axis

[RFC] ENH: Add axis argument to dwt

doc/source/dev/testing.rst

@@ -42,5 +42,5 @@ To for example run tests for Python 2.7 and Python 3.4 use::
 For more information see the `Tox`_ documentation.
 
 
-.. _nose: http://nose.readthedocs.org/en/latest/ 
-.. _Tox: http://tox.testrun.org/ 
+.. _nose: http://nose.readthedocs.org/en/latest/
+.. _Tox: http://tox.testrun.org/

doc/source/ref/dwt-discrete-wavelet-transform.rst

@@ -15,7 +15,7 @@ functions used to perform single- and multilevel Discrete Wavelet Transforms.
 Single level ``dwt``
 --------------------
 
-.. function:: dwt(data, wavelet[, mode='symmetric'])
+.. function:: dwt(data, wavelet[, mode='symmetric', axis=-1])
 
   The :func:`dwt` function is used to perform single level, one dimensional
   Discrete Wavelet Transform.
@@ -30,6 +30,8 @@ Single level ``dwt``
 
   :param mode: |mode|
 
+  :param axis: |axis|
+
   The transform coefficients are returned as two arrays containing
   approximation (*cA*) and detail (*cD*) coefficients respectively. Length
   of returned arrays depends on the selected signal extension *mode* - see
@@ -45,6 +47,10 @@ Single level ``dwt``
 
       len(cA) == len(cD) == ceil(len(data) / 2)
 
+  The transform can be performed over one axis of multi-dimensional
+  data. By default this is the last axis. For multi-dimensional transforms
+  see the :ref:`2D transforms <ref-dwt2>` section.
+
   **Example:**
 
   .. sourcecode:: python

doc/source/ref/idwt-inverse-discrete-wavelet-transform.rst

@@ -11,7 +11,7 @@ Inverse Discrete Wavelet Transform (IDWT)
 Single level ``idwt``
 ---------------------
 
-.. function:: idwt(cA, cD, wavelet[, mode='symmetric'[, correct_size=0]])
+.. function:: idwt(cA, cD, wavelet[, mode='symmetric', axis=-1])
 
   The :func:`idwt` function reconstructs data from the given coefficients by
   performing single level Inverse Discrete Wavelet Transform.
@@ -25,15 +25,8 @@ Single level ``idwt``
   :param mode: |mode| This is only important when DWT was performed in
                :ref:`periodization <Modes.periodization>` mode.
 
-  :param correct_size: Typically, *cA* and *cD* coefficients lists must have
-                       equal lengths in order to perform IDWT. Setting
-                       *correct_size* to `True` allows *cA* to be greater in
-                       size by one element compared to the *cD* size. This
-                       option is very useful when doing multilevel decomposition
-                       and reconstruction (as for example with the
-                       :func:`wavedec` function) of non-dyadic length signals
-                       when such minor differences can occur at various levels
-                       of IDWT.
+  :param axis: |axis| This should be the same as the axis used in the
+               DWT that produced the coefficients.
 
   **Example:**
 
@@ -96,7 +89,7 @@ Direct reconstruction with ``upcoef``
   Direct reconstruction from coefficients.
 
   :param part: Defines the input coefficients type:
-  
+
       - **'a'** - approximations reconstruction is performed
       - **'d'** - details reconstruction is performed
 

doc/source/ref/other-functions.rst

@@ -22,7 +22,7 @@ Single-level n-dimensional Discrete Wavelet Transform.
    Results are arranged in a dictionary, where key specifies
    the transform type on each dimension and value is a n-dimensional
    coefficients array.
-    
+
    For example, for a 2D case the result will look something like this::
 
       {

doc/source/regression/dwt-idwt.rst

@@ -138,19 +138,6 @@ must have the same size.
     ...
     ValueError: Coefficients arrays must have the same size.
 
-But for some applications like multilevel DWT and IDWT it is sometimes convenient
-to allow for a small departure from this behaviour. When the *correct_size* flag
-is set, the approximation coefficients array can be larger from the details
-coefficient array by one element:
-
-    >>> print pywt.idwt([1, 2, 3, 4, 5], [1, 2, 3, 4], 'db2', 'symmetric', correct_size=True)
-    [ 1.76776695  0.61237244  3.18198052  0.61237244  4.59619408  0.61237244]
-
-    >>> print pywt.idwt([1, 2, 3, 4], [1, 2, 3, 4, 5], 'db2', 'symmetric', correct_size=True)
-    Traceback (most recent call last):
-    ...
-    ValueError: Coefficients arrays must satisfy (0 <= len(cA) - len(cD) <= 1).
-
 
 Not every coefficient array can be used in :func:`IDWT <idwt>`. In the
 following example the :func:`idwt` will fail because the input arrays are

doc/source/substitutions.rst

@@ -5,3 +5,6 @@
 
 .. |wavelet| replace::
    Wavelet to use in the transform. This can be a name of the wavelet from the :func:`wavelist` list or a :class:`Wavelet` object instance.
+
+.. |axis| replace::
+   Axis to perform the transform over, in the case of multi-dimensional input.