DOC: better document how to handle omitted coefficients in multilevel DWT reconstructions

pywt/_multidim.py

@@ -192,12 +192,16 @@ def dwtn(data, wavelet, mode='symmetric', axes=None):
 
 
 def _fix_coeffs(coeffs):
-    missing_keys = [k for k, v in coeffs.items() if
-                    v is None]
+    missing_keys = [k for k, v in coeffs.items() if v is None]
     if missing_keys:
         raise ValueError(
-            "The following detail coefficients were set to None: "
-            "{}.".format(missing_keys))
+            "The following detail coefficients were set to None:\n"
+            "{0}\n"
+            "For multilevel transforms, rather than setting\n"
+            "\tcoeffs[key] = None\n"
+            "use\n"
+            "\tcoeffs[key] = np.zeros_like(coeffs[key])\n".format(
+                missing_keys))
 
     invalid_keys = [k for k, v in coeffs.items() if
                     not set(k) <= set('ad')]

pywt/_multilevel.py

@@ -122,6 +122,17 @@ def waverec(coeffs, wavelet, mode='symmetric', axis=-1):
         Axis over which to compute the inverse DWT. If not given, the
         last axis is used.
 
+    Notes
+    -----
+    It may sometimes desired to run ``waverec`` with some sets of
+    coefficients omitted.  This can best be done by setting the corresponding
+    arrays to zero arrays of matching shape and dtype.  Explicitly removing
+    list entries or setting them to ``None`` is not supported.
+
+    Specifically, to ignore detail coefficients at level 2, one could do::
+
+        coeffs[-2] == numpy.zeros_like(coeffs[-2])
+
     Examples
     --------
     >>> import pywt
@@ -251,6 +262,17 @@ def waverec2(coeffs, wavelet, mode='symmetric', axes=(-2, -1)):
     -------
     2D array of reconstructed data.
 
+    Notes
+    -----
+    It may sometimes desired to run ``waverec2`` with some sets of
+    coefficients omitted.  This can best be done by setting the corresponding
+    arrays to zero arrays of matching shape and dtype.  Explicitly removing
+    list or tuple entries or setting them to ``None`` is not supported.
+
+    Specifically, to ignore all detail coefficients at level 2, one could do::
+
+        coeffs[-2] == tuple([numpy.zeros_like(v) for v in coeffs[-2]])
+
     Examples
     --------
     >>> import pywt
@@ -436,6 +458,17 @@ def waverecn(coeffs, wavelet, mode='symmetric', axes=None):
     -------
     nD array of reconstructed data.
 
+    Notes
+    -----
+    It is sometimes desired to run ``waverecn`` with some sets of
+    coefficients omitted.  This can best be done by setting the corresponding
+    arrays to zero arrays of matching shape and dtype.  Explicitly removing
+    list or dictionary entries or setting them to ``None`` is not supported.
+
+    Specifically, to ignore all detail coefficients at level 2, one could do::
+
+        codffs[-2] = {k: numpy.zeros_like(v) for k, v in coeffs[-2].items()}
+
     Examples
     --------
     >>> import numpy as np