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
coeffsarray-like

Dictionary of wavelet coefficients as returned by pywt.wavedecn

paddingfloat or None, optional

The value to use for the background if the coefficients cannot be tightly packed. If None, raise an error if the coefficients cannot be tightly packed.

axessequence of ints, optional

Axes over which the DWT that created coeffs was performed. The default value of None corresponds to all axes.

Returns
coeff_arrarray-like

Wavelet transform coefficient array.

coeff_sliceslist

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']          |
|                               |                               |
|                               |                               |
|                               |                               |
+-------------------------------+-------------------------------+

If the transform was not performed with mode “periodization” or the signal length was not a multiple of 2**level, coefficients at each subsequent scale will not be exactly 1/2 the size of those at the previous level due to additional coefficients retained to handle the boundary condition. In these cases, the default setting of padding=0 indicates to pad the individual coefficient arrays with 0 as needed so that they can be stacked into a single, contiguous array.

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
arrarray-like

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

coeff_sliceslist 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
coeffsarray-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.

axessequence of ints, optional

Axes over which the DWT that created coeffs was performed. The default value of None corresponds to all axes.

Returns
coeff_arrarray-like

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

coeff_sliceslist

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_shapeslist

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
arrarray-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_sliceslist of tuples

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

coeff_shapeslist 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
shapeslist 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
sizeint

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
shapesequence of ints

The shape of the data to be transformed.

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

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

levelint, optional

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

axessequence 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}]list

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)}]