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 [1]. 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.