# Stationary Wavelet Transform¶

Stationary Wavelet Transform (SWT), also known as Undecimated wavelet transform or Algorithme à trous is a translation-invariance modification of the Discrete Wavelet Transform that does not decimate coefficients at every transformation level.

## Multilevel 1D `swt`¶

pywt.swt(data, wavelet, level=None, start_level=0, axis=-1, trim_approx=False, norm=False)

Multilevel 1D stationary wavelet transform.

Parameters
data

Input signal

wavelet

Wavelet to use (Wavelet object or name)

levelint, optional

The number of decomposition steps to perform.

start_levelint, optional

The level at which the decomposition will begin (it allows one to skip a given number of transform steps and compute coefficients starting from start_level) (default: 0)

axis: int, optional

Axis over which to compute the SWT. If not given, the last axis is used.

trim_approxbool, optional

If True, approximation coefficients at the final level are retained.

normbool, optional

If True, transform is normalized so that the energy of the coefficients will be equal to the energy of `data`. In other words, `np.linalg.norm(data.ravel())` will equal the norm of the concatenated transform coefficients when `trim_approx` is True.

Returns
coeffslist

List of approximation and details coefficients pairs in order similar to wavedec function:

```[(cAn, cDn), ..., (cA2, cD2), (cA1, cD1)]
```

where n equals input parameter `level`.

If `start_level = m` is given, then the beginning m steps are skipped:

```[(cAm+n, cDm+n), ..., (cAm+1, cDm+1), (cAm, cDm)]
```

If `trim_approx` is `True`, then the output list is exactly as in `pywt.wavedec`, where the first coefficient in the list is the approximation coefficient at the final level and the rest are the detail coefficients:

```[cAn, cDn, ..., cD2, cD1]
```

Notes

The implementation here follows the “algorithm a-trous” and requires that the signal length along the transformed axis be a multiple of `2**level`. If this is not the case, the user should pad up to an appropriate size using a function such as `numpy.pad`.

A primary benefit of this transform in comparison to its decimated counterpart (`pywt.wavedecn`), is that it is shift-invariant. This comes at cost of redundancy in the transform (the size of the output coefficients is larger than the input).

When the following three conditions are true:

1. The wavelet is orthogonal

2. `swt` is called with `norm=True`

3. `swt` is called with `trim_approx=True`

the transform has the following additional properties that may be desirable in applications:

1. energy is conserved

2. variance is partitioned across scales

When used with `norm=True`, this transform is closely related to the multiple-overlap DWT (MODWT) as popularized for time-series analysis, although the underlying implementation is slightly different from the one published in . Specifically, the implementation used here requires a signal that is a multiple of `2**level` in length.

References

1

DB Percival and AT Walden. Wavelet Methods for Time Series Analysis. Cambridge University Press, 2000.

## Multilevel 2D `swt2`¶

pywt.swt2(data, wavelet, level, start_level=0, axes=(-2, -1), trim_approx=False, norm=False)

Multilevel 2D stationary wavelet transform.

Parameters
dataarray_like

2D array with input data

waveletWavelet object or name string, or 2-tuple of wavelets

Wavelet to use. This can also be a tuple of wavelets to apply per axis in `axes`.

levelint

The number of decomposition steps to perform.

start_levelint, optional

The level at which the decomposition will start (default: 0)

axes2-tuple of ints, optional

Axes over which to compute the SWT. Repeated elements are not allowed.

trim_approxbool, optional

If True, approximation coefficients at the final level are retained.

normbool, optional

If True, transform is normalized so that the energy of the coefficients will be equal to the energy of `data`. In other words, `np.linalg.norm(data.ravel())` will equal the norm of the concatenated transform coefficients when `trim_approx` is True.

Returns
coeffslist

Approximation and details coefficients (for `start_level = m`). If `trim_approx` is `False`, approximation coefficients are retained for all levels:

```[
(cA_m+level,
(cH_m+level, cV_m+level, cD_m+level)
),
...,
(cA_m+1,
(cH_m+1, cV_m+1, cD_m+1)
),
(cA_m,
(cH_m, cV_m, cD_m)
)
]
```

where cA is approximation, cH is horizontal details, cV is vertical details, cD is diagonal details and m is `start_level`.

If `trim_approx` is `True`, approximation coefficients are only retained at the final level of decomposition. This matches the format used by `pywt.wavedec2`:

```[
cA_m+level,
(cH_m+level, cV_m+level, cD_m+level),
...,
(cH_m+1, cV_m+1, cD_m+1),
(cH_m, cV_m, cD_m),
]
```

Notes

The implementation here follows the “algorithm a-trous” and requires that the signal length along the transformed axes be a multiple of `2**level`. If this is not the case, the user should pad up to an appropriate size using a function such as `numpy.pad`.

A primary benefit of this transform in comparison to its decimated counterpart (`pywt.wavedecn`), is that it is shift-invariant. This comes at cost of redundancy in the transform (the size of the output coefficients is larger than the input).

When the following three conditions are true:

1. The wavelet is orthogonal

2. `swt2` is called with `norm=True`

3. `swt2` is called with `trim_approx=True`

the transform has the following additional properties that may be desirable in applications:

1. energy is conserved

2. variance is partitioned across scales

## Multilevel n-dimensional `swtn`¶

pywt.swtn(data, wavelet, level, start_level=0, axes=None, trim_approx=False, norm=False)

n-dimensional stationary wavelet transform.

Parameters
dataarray_like

n-dimensional array with input data.

waveletWavelet object or name string, or tuple of wavelets

Wavelet to use. This can also be a tuple of wavelets to apply per axis in `axes`.

levelint

The number of decomposition steps to perform.

start_levelint, optional

The level at which the decomposition will start (default: 0)

axessequence of ints, optional

Axes over which to compute the SWT. A value of `None` (the default) selects all axes. Axes may not be repeated.

trim_approxbool, optional

If True, approximation coefficients at the final level are retained.

normbool, optional

If True, transform is normalized so that the energy of the coefficients will be equal to the energy of `data`. In other words, `np.linalg.norm(data.ravel())` will equal the norm of the concatenated transform coefficients when `trim_approx` is True.

Returns
[{coeffs_level_n}, …, {coeffs_level_1}]: list of dict

Results for each level are arranged in a dictionary, where the key specifies the transform type on each dimension and value is a n-dimensional coefficients array.

For example, for a 2D case the result at a given level will look something like this:

```{'aa': <coeffs>  # A(LL) - approx. on 1st dim, approx. on 2nd dim
'ad': <coeffs>  # V(LH) - approx. on 1st dim, det. on 2nd dim
'da': <coeffs>  # H(HL) - det. on 1st dim, approx. on 2nd dim
'dd': <coeffs>  # D(HH) - det. on 1st dim, det. on 2nd dim
}
```

For user-specified `axes`, the order of the characters in the dictionary keys map to the specified `axes`.

If `trim_approx` is `True`, the first element of the list contains the array of approximation coefficients from the final level of decomposition, while the remaining coefficient dictionaries contain only detail coefficients. This matches the behavior of pywt.wavedecn.

Notes

The implementation here follows the “algorithm a-trous” and requires that the signal length along the transformed axes be a multiple of `2**level`. If this is not the case, the user should pad up to an appropriate size using a function such as `numpy.pad`.

A primary benefit of this transform in comparison to its decimated counterpart (`pywt.wavedecn`), is that it is shift-invariant. This comes at cost of redundancy in the transform (the size of the output coefficients is larger than the input).

When the following three conditions are true:

1. The wavelet is orthogonal

2. `swtn` is called with `norm=True`

3. `swtn` is called with `trim_approx=True`

the transform has the following additional properties that may be desirable in applications:

1. energy is conserved

2. variance is partitioned across scales

## Maximum decomposition level - `swt_max_level`¶

pywt.swt_max_level(input_len)

Calculates the maximum level of Stationary Wavelet Transform for data of given length.

Parameters
input_lenint

Input data length.

Returns
max_levelint

Maximum level of Stationary Wavelet Transform for data of given length.

Notes

For the current implementation of the stationary wavelet transform, this corresponds to the number of times `input_len` is evenly divisible by two. In other words, for an n-level transform, the signal length must be a multiple of `2**n`. `numpy.pad` can be used to pad a signal up to an appropriate length as needed.