Handling DWT Coefficients

Convenience routines are available for converting the outputs of the multilevel dwt functions (wavedec, wavedec2 and wavedecn) to and from a single, concatenated coefficient array.

Concatenating all coefficients into a single n-d array

pywt.coeffs_to_array(coeffs, padding=0, axes=None)

Arrange a wavelet coefficient list from wavedecn into a single array.

Parameters:
coeffs : array-like

dictionary of wavelet coefficients as returned by pywt.wavedecn

padding : float or None, optional

If None, raise an error if the coefficients cannot be tightly packed.

axes : sequence of ints, optional

Axes over which the DWT that created coeffs was performed. The default value of None corresponds to all axes.
Returns:
coeff_arr : array-like

Wavelet transform coefficient array.

coeff_slices : list

List of slices corresponding to each coefficient. As a 2D example, coeff_arr[coeff_slices[1]['dd']] would extract the first level detail coefficients from coeff_arr.

See also

array_to_coeffs
the inverse of coeffs_to_array

Notes

Assume a 2D coefficient dictionary, c, from a two-level transform.

Then all 2D coefficients will be stacked into a single larger 2D array as follows:

+---------------+---------------+-------------------------------+
|               |               |                               |
|     c[0]      |  c[1]['da']   |                               |
|               |               |                               |
+---------------+---------------+           c[2]['da']          |
|               |               |                               |
| c[1]['ad']    |  c[1]['dd']   |                               |
|               |               |                               |
+---------------+---------------+ ------------------------------+
|                               |                               |
|                               |                               |
|                               |                               |
|          c[2]['ad']           |           c[2]['dd']          |
|                               |                               |
|                               |                               |
|                               |                               |
+-------------------------------+-------------------------------+

Examples

>>> import pywt
>>> cam = pywt.data.camera()
>>> coeffs = pywt.wavedecn(cam, wavelet='db2', level=3)
>>> arr, coeff_slices = pywt.coeffs_to_array(coeffs)

Splitting concatenated coefficient array back into its components

pywt.array_to_coeffs(arr, coeff_slices, output_format='wavedecn')

Convert a combined array of coefficients back to a list compatible with waverecn.

Parameters:
arr : array-like

An array containing all wavelet coefficients. This should have been generated via coeffs_to_array.

coeff_slices : list of tuples

List of slices corresponding to each coefficient as obtained from array_to_coeffs.

output_format : {‘wavedec’, ‘wavedec2’, ‘wavedecn’}

Make the form of the coefficients compatible with this type of multilevel transform.
Returns:
coeffs: array-like

Wavelet transform coefficient array.

See also

coeffs_to_array
the inverse of array_to_coeffs

Notes

A single large array containing all coefficients will have subsets stored, into a waverecn list, c, as indicated below:

+---------------+---------------+-------------------------------+
|               |               |                               |
|     c[0]      |  c[1]['da']   |                               |
|               |               |                               |
+---------------+---------------+           c[2]['da']          |
|               |               |                               |
| c[1]['ad']    |  c[1]['dd']   |                               |
|               |               |                               |
+---------------+---------------+ ------------------------------+
|                               |                               |
|                               |                               |
|                               |                               |
|          c[2]['ad']           |           c[2]['dd']          |
|                               |                               |
|                               |                               |
|                               |                               |
+-------------------------------+-------------------------------+

Examples

>>> import pywt
>>> from numpy.testing import assert_array_almost_equal
>>> cam = pywt.data.camera()
>>> coeffs = pywt.wavedecn(cam, wavelet='db2', level=3)
>>> arr, coeff_slices = pywt.coeffs_to_array(coeffs)
>>> coeffs_from_arr = pywt.array_to_coeffs(arr, coeff_slices,
...                                        output_format='wavedecn')
>>> cam_recon = pywt.waverecn(coeffs_from_arr, wavelet='db2')
>>> assert_array_almost_equal(cam, cam_recon)

Raveling and unraveling coefficients to/from a 1D array

pywt.ravel_coeffs(coeffs, axes=None)

Ravel a set of multilevel wavelet coefficients into a single 1D array.

Parameters:
coeffs : array-like

A list of multilevel wavelet coefficients as returned by wavedec, wavedec2 or wavedecn. This function is also compatible with the output of swt, swt2 and swtn if those functions were called with trim_approx=True.

axes : sequence of ints, optional

Axes over which the DWT that created coeffs was performed. The default value of None corresponds to all axes.
Returns:
coeff_arr : array-like

Wavelet transform coefficient array. All coefficients have been concatenated into a single array.

coeff_slices : list

List of slices corresponding to each coefficient. As a 2D example, coeff_arr[coeff_slices[1]['dd']] would extract the first level detail coefficients from coeff_arr.

coeff_shapes : list

List of shapes corresponding to each coefficient. For example, in 2D, coeff_shapes[1]['dd'] would contain the original shape of the first level detail coefficients array.

See also

unravel_coeffs
the inverse of ravel_coeffs

Examples

>>> import pywt
>>> cam = pywt.data.camera()
>>> coeffs = pywt.wavedecn(cam, wavelet='db2', level=3)
>>> arr, coeff_slices, coeff_shapes = pywt.ravel_coeffs(coeffs)
pywt.unravel_coeffs(arr, coeff_slices, coeff_shapes, output_format='wavedecn')

Unravel a raveled array of multilevel wavelet coefficients.

Parameters:
arr : array-like

An array containing all wavelet coefficients. This should have been generated by applying ravel_coeffs to the output of wavedec, wavedec2 or wavedecn (or via swt, swt2 or swtn with trim_approx=True).

coeff_slices : list of tuples

List of slices corresponding to each coefficient as obtained from ravel_coeffs.

coeff_shapes : list of tuples

List of shapes corresponding to each coefficient as obtained from ravel_coeffs.

output_format : {‘wavedec’, ‘wavedec2’, ‘wavedecn’, ‘swt’, ‘swt2’, ‘swtn’}, optional

Make the form of the unraveled coefficients compatible with this type of multilevel transform. The default is 'wavedecn'.
Returns:
coeffs: list

List of wavelet transform coefficients. The specific format of the list elements is determined by output_format.

See also

ravel_coeffs
the inverse of unravel_coeffs

Examples

>>> import pywt
>>> from numpy.testing import assert_array_almost_equal
>>> cam = pywt.data.camera()
>>> coeffs = pywt.wavedecn(cam, wavelet='db2', level=3)
>>> arr, coeff_slices, coeff_shapes = pywt.ravel_coeffs(coeffs)
>>> coeffs_from_arr = pywt.unravel_coeffs(arr, coeff_slices, coeff_shapes,
...                                       output_format='wavedecn')
>>> cam_recon = pywt.waverecn(coeffs_from_arr, wavelet='db2')
>>> assert_array_almost_equal(cam, cam_recon)

Multilevel: Total size of all coefficients - wavedecn_size

pywt.wavedecn_size(shapes)

Compute the total number of wavedecn coefficients.

Parameters:
shapes : list of coefficient shapes

A set of coefficient shapes as returned by wavedecn_shapes. Alternatively, the user can specify a set of coefficients as returned by wavedecn.
Returns:
size : int

The total number of coefficients.

Examples

>>> import numpy as np
>>> import pywt
>>> data_shape = (64, 32)
>>> shapes = pywt.wavedecn_shapes(data_shape, 'db2', mode='periodization')
>>> pywt.wavedecn_size(shapes)
2048
>>> coeffs = pywt.wavedecn(np.ones(data_shape), 'sym4', mode='symmetric')
>>> pywt.wavedecn_size(coeffs)
3087

Multilevel: n-d coefficient shapes - wavedecn_shapes

pywt.wavedecn_shapes(shape, wavelet, mode='symmetric', level=None, axes=None)

Subband shapes for a multilevel nD discrete wavelet transform.

Parameters:
shape : sequence of ints

The shape of the data to be transformed.

wavelet : Wavelet object or name string, or tuple of wavelets

Wavelet to use. This can also be a tuple containing a wavelet to apply along each axis in axes.

mode : str or tuple of str, optional

Signal extension mode, see Modes. This can also be a tuple containing a mode to apply along each axis in axes.

level : int, optional

Decomposition level (must be >= 0). If level is None (default) then it will be calculated using the dwt_max_level function.

axes : sequence of ints, optional

Axes over which to compute the DWT. Axes may not be repeated. The default is None, which means transform all axes (axes = range(data.ndim)).
Returns:
shapes : [cAn, {details_level_n}, … {details_level_1}]

Coefficients shape list. Mirrors the output of wavedecn, except it contains only the shapes of the coefficient arrays rather than the arrays themselves.

Examples

>>> import pywt
>>> pywt.wavedecn_shapes((64, 32), wavelet='db2', level=3, axes=(0, ))
[(10, 32), {'d': (10, 32)}, {'d': (18, 32)}, {'d': (33, 32)}]