# 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¶

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['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']   |                               |
|               |               |                               |
+---------------+---------------+ ------------------------------+
|                               |                               |
|                               |                               |
|                               |                               |
|          c['ad']           |           c['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.

`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']   |                               |
|               |               |                               |
+---------------+---------------+ ------------------------------+
|                               |                               |
|                               |                               |
|                               |                               |
|          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
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['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['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
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`.

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