# 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. 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['dd']] would extract the first level detail coefficients from coeff_arr.

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      |  c['da']   |                               |
|               |               |                               |
+---------------+---------------+           c['da']          |
|               |               |                               |
| c['ad']    |  c['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. coeffs: array-like Wavelet transform coefficient array.

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      |  c['da']   |                               |
|               |               |                               |
+---------------+---------------+           c['da']          |
|               |               |                               |
| c['ad']    |  c['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. 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['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['dd'] would contain the original shape of the first level detail coefficients array.

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'. coeffs: list List of wavelet transform coefficients. The specific format of the list elements is determined by output_format.

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