Fast Wavelet Transform (FWT) using padded convolutions

Fast Wavelet Transform (FWT) using padded convolutions#

1d decomposition using wavedec()#

ptwt.wavedec(data: Tensor, wavelet: Wavelet | str, *, mode: ptwt.constants.BoundaryMode = 'reflect', level: int | None = None, axis: int = -1) → list[Tensor][source]#

Compute the analysis (forward) 1d fast wavelet transform.

The transformation relies on convolution operations with the filter pair \((\mathbf{h}_A, \mathbf{h}_D)\) of the wavelet where \(A\) denotes approximation and \(D\) detail. The coefficients on level \(s\) are calculated iteratively as

\[\mathbf{c}_{k,s} = \mathbf{c}_{A,s - 1} * \mathbf{h}_k \quad \text{for $k\in\{A, D\}$}\]

with \(\mathbf{c}_{A, 0} = \mathbf{x}_0\) the original input signal. The process uses approximation coefficients as inputs for higher scales. Set the level argument to choose the largest scale.

Parameters:

  • data (torch.Tensor) – The input time series to transform. By default the last axis is transformed.

  • wavelet (Wavelet or str) – A pywt wavelet compatible object or the name of a pywt wavelet. Please consider the output from pywt.wavelist(kind='discrete') for possible choices.

  • mode – The desired padding mode for extending the signal along the edges. See ptwt.constants.BoundaryMode. Defaults to reflect.

  • level (int, optional) – The maximum decomposition level. If None, the level is computed based on the signal shape. Defaults to None.

  • axis (int) – Compute the transform over this axis of the data tensor. Defaults to -1.

Returns:

A list:

[cA_n, cD_n, cD_n-1, …, cD2, cD1]

containing the wavelet coefficient tensors where n denotes the level of decomposition. The first entry of the list (cA_n) is the approximation coefficient tensor. The following entries (cD_n - cD1) are the detail coefficient tensors of the respective level.

Example

>>> import ptwt, torch
>>> # generate an input of even length.
>>> data = torch.arange(8, dtype=torch.float32)
>>> # compute the forward fwt coefficients
>>> ptwt.wavedec(data, 'haar', mode='zero', level=2)

2d decomposition using wavedec2()#

ptwt.wavedec2(data: Tensor, wavelet: Wavelet | str, *, mode: ptwt.constants.BoundaryMode = 'reflect', level: int | None = None, axes: tuple[int, int] = (-2, -1)) → ptwt.constants.WaveletCoeff2d[source]#

Compute the two-dimensional fast wavelet transformation.

This function relies on two-dimensional convolutions. Outer products allow the construction of 2d filters \(\mathbf{h}_k\) for \(k\in\{a, h, v, d\}\) from the 1d filter pair of the wavelet where \(a\) denotes approximation, \(h\) horizontal details, \(v\) vertical details, and \(d\) diagonal details. See the FWT intro.

The coefficients on level \(s\) are calculated iteratively as

\[\mathbf{c}_{k, s} = \mathbf{c}_{a, s-1} *_2 \mathbf{h}_k \quad \text{for $k \in \{a, h, v, d\}$}\]

with \(\mathbf{c}_{a, 0} = \mathbf{x}_0\) the original input image. \(*_2\) indicates two dimensional-convolution. Set the level argument to choose the largest scale.

Parameters:

  • data (torch.Tensor) – The input data tensor with at least two dimensions. By default, the last two axes are transformed.

  • wavelet (Wavelet or str) – A pywt wavelet compatible object or the name of a pywt wavelet. Refer to the output from pywt.wavelist(kind='discrete') for possible choices.

  • mode – The desired padding mode for extending the signal along the edges. See ptwt.constants.BoundaryMode. Defaults to reflect.

  • level (int, optional) – The maximum decomposition level. If None, the level is computed based on the signal shape. Defaults to None.

  • axes (tuple[int, int]) – Compute the transform over these axes of the data tensor. Defaults to (-2, -1).

Returns:

A tuple containing the wavelet coefficients in pywt order, see ptwt.constants.WaveletCoeff2d.

Example

>>> import ptwt, torch
>>> from scipy import datasets
>>> data = torch.tensor(datasets.face(), dtype=torch.float64)
>>> # permute [H, W, C] -> [C, H, W]
>>> data = data.permute(2, 0, 1)
>>> # compute the FWT coefficients
>>> coefficients = ptwt.wavedec2(data, "haar", level=2, mode="zero")

3d decomposition using wavedec3()#

ptwt.wavedec3(data: Tensor, wavelet: Wavelet | str, *, mode: ptwt.constants.BoundaryMode = 'zero', level: int | None = None, axes: tuple[int, int, int] = (-3, -2, -1)) → ptwt.constants.WaveletCoeffNd[source]#

Compute the three-dimensional fast wavelet transformation.

Parameters:

  • data (torch.Tensor) – The input data tensor with at least three dimensions. By default, the last three axes are transformed.

  • wavelet (Wavelet or str) – A pywt wavelet compatible object or the name of a pywt wavelet. Refer to the output from pywt.wavelist(kind='discrete') for possible choices.

  • mode – The desired padding mode for extending the signal along the edges. See ptwt.constants.BoundaryMode. Defaults to zero.

  • level (int, optional) – The maximum decomposition level. If None, the level is computed based on the signal shape. Defaults to None.

  • axes (tuple[int, int, int]) – Compute the transform over these axes of the data tensor. Defaults to (-3, -2, -1).

Returns:

A tuple containing the wavelet coefficients, see ptwt.constants.WaveletCoeffNd.

Example

>>> import ptwt, torch
>>> data = torch.randn(5, 16, 16, 16)
>>> transformed = ptwt.wavedec3(data, "haar", level=2, mode="reflect")

Fully separable 2d decomposition using fswavedec2()#

ptwt.fswavedec2(data: Tensor, wavelet: Wavelet | str, *, mode: ptwt.constants.BoundaryMode = 'reflect', level: int | None = None, axes: tuple[int, int] = (-2, -1)) → ptwt.constants.WaveletCoeff2dSeparable[source]#

Compute a fully separable 2D-padded analysis wavelet transform.

Single-dimensional convolutions are used to transform each axis individually. Under the hood, all dimensions are transformed using torch.nn.functional.conv1d().

Parameters:

  • data (torch.Tensor) – The input data tensor with at least two dimensions. By default, the last two axes are transformed.

  • wavelet (Wavelet or str) – A pywt wavelet compatible object or the name of a pywt wavelet. Refer to the output of pywt.wavelist(kind="discrete") for a list of possible choices.

  • mode – The desired padding mode for extending the signal along the edges. See ptwt.constants.BoundaryMode. Defaults to reflect.

  • level (int, optional) – The maximum decomposition level. If None, the level is computed based on the signal shape. Defaults to None.

  • axes (tuple[int, int]) – Compute the transform over these axes of the data tensor. Defaults to (-2, -1).

Returns:

A tuple starting with the approximation coefficient tensor followed by a dictionary of detail coefficients for each scale, see ptwt.constants.WaveletCoeff2dSeparable. The dictionaries use the filter order strings:

"ad", "da", "dd"

as keys. a denotes the low pass or approximation filter and d the high-pass or detail filter.

Example

>>> import ptwt, torch
>>> data = torch.randn(5, 10, 10)
>>> coeff = ptwt.fswavedec2(data, "haar", level=2)

Fully separable 3d decomposition using fswavedec3()#

ptwt.fswavedec3(data: Tensor, wavelet: Wavelet | str, *, mode: ptwt.constants.BoundaryMode = 'reflect', level: int | None = None, axes: tuple[int, int, int] = (-3, -2, -1)) → ptwt.constants.WaveletCoeffNd[source]#

Compute a fully separable 3D-padded analysis wavelet transform.

Single-dimensional convolutions are used to transform each axis individually. Under the hood, all dimensions are transformed using torch.nn.functional.conv1d().

Parameters:

  • data (torch.Tensor) – The input data tensor with at least three dimensions. By default, the last three axes are transformed.

  • wavelet (Wavelet or str) – A pywt wavelet compatible object or the name of a pywt wavelet. Refer to the output of pywt.wavelist(kind="discrete") for possible choices.

  • mode – The desired padding mode for extending the signal along the edges. See ptwt.constants.BoundaryMode. Defaults to reflect.

  • level (int, optional) – The maximum decomposition level. If None, the level is computed based on the signal shape. Defaults to None.

  • axes (tuple[int, int, int]) – Compute the transform over these axes of the data tensor. Defaults to (-3, -2, -1).

Returns:

A tuple starting with the approximation coefficient tensor followed by a dictionary of detail coefficients for each scale, see ptwt.constants.WaveletCoeffNd. The dictionaries use the filter order strings:

"aad", "ada", "add", "daa", "dad", "dda", "ddd"

as keys. a denotes the low pass or approximation filter and d the high-pass or detail filter.

Example

>>> import ptwt, torch
>>> data = torch.randn(5, 10, 10, 10)
>>> coeff = ptwt.fswavedec3(data, "haar", level=2)
Contents