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)
>>> 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.

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.

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’}, 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)
>>> 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 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 (default: ‘symmetric’). 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)}]