Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions doc/source/ref/other-functions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ Other functions
===============


Discrete scaling function refinement
------------------------------------

.. autofunction:: refinement_matrix


Integrating wavelet functions
-----------------------------

Expand Down
55 changes: 54 additions & 1 deletion pywt/_functions.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@

__all__ = ["integrate_wavelet", "central_frequency",
"scale2frequency", "frequency2scale", "qmf",
"orthogonal_filter_bank",
"orthogonal_filter_bank", "refinement_matrix",
"intwave", "centrfrq", "scal2frq", "orthfilt"]


Expand Down Expand Up @@ -55,6 +55,59 @@ def orthfilt(*args, **kwargs):
return orthogonal_filter_bank(*args, **kwargs)


def refinement_matrix(wavelet, *, dual=False):
r"""Return the integer-grid refinement matrix of a discrete wavelet.

Parameters
----------
wavelet : Wavelet or str
Discrete wavelet object or name.
dual : bool, optional
Use the dual scaling function. Its synthesis filter is the
time-reversed decomposition low-pass filter. The default uses the
reconstruction low-pass filter.

Returns
-------
matrix : ndarray
Square matrix with one row and column for each low-pass filter tap.
Filter indices, including any zero padding, are preserved.

Notes
-----
For a synthesis filter :math:`h` of length :math:`L`, the entry at
:math:`(n,k)` is :math:`\sqrt{2}\,h[2n-k]`, with taps outside
:math:`[0,L-1]` taken as zero. The two-scale equation implies that the
integer samples of a continuous scaling function form a fixed point of
this matrix. If the scaling function is differentiable, the samples of
its derivative have eigenvalue 1/2.

Examples
--------
The reconstruction scaling function of ``bior2.2`` is a linear B-spline.
At integer filter-grid positions its peak lies at index 2:

>>> import numpy as np
>>> import pywt
>>> M = pywt.refinement_matrix('bior2.2')
>>> samples = np.eye(M.shape[0])[2]
>>> np.allclose(M @ samples, samples)
True
"""
if isinstance(wavelet, str):
wavelet = Wavelet(wavelet)
if not isinstance(wavelet, Wavelet):
raise TypeError("refinement_matrix requires a discrete wavelet")

h = np.asarray(wavelet.dec_lo[::-1] if dual else wavelet.rec_lo)
grid = np.arange(h.size)
taps = 2 * grid[:, None] - grid
inside = (taps >= 0) & (taps < h.size)
matrix = np.zeros((h.size, h.size))
matrix[inside] = np.sqrt(2) * h[taps[inside]]
return matrix


def integrate_wavelet(wavelet, precision=8):
"""
Integrate `psi` wavelet function from -Inf to x using the rectangle
Expand Down
32 changes: 32 additions & 0 deletions pywt/tests/test_refinement_matrix.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
import numpy as np
import pytest
from numpy.testing import assert_allclose

import pywt


@pytest.mark.parametrize('name', ['haar', 'db4', 'bior2.2', 'bior3.3', 'rbio4.4'])
@pytest.mark.parametrize('dual', [False, True])
def test_refinement_operator(name, dual):
wavelet = pywt.Wavelet(name)
h = wavelet.inverse_filter_bank[2] if dual else wavelet.rec_lo
x = np.arange(1, len(h) + 1, dtype=float)
expected = np.sqrt(2) * np.convolve(h, x)[::2]
assert_allclose(pywt.refinement_matrix(name, dual=dual) @ x, expected)


def test_cardinal_cubic_spline():
# The cubic B-spline mask, padded to an even filter length.
h = np.array([1, 4, 6, 4, 1, 0]) / (8 * np.sqrt(2))
zeros = np.zeros_like(h)
wavelet = pywt.Wavelet('spline', filter_bank=[h[::-1], zeros, h, zeros])
matrix = pywt.refinement_matrix(wavelet)
phi = np.array([0, 1, 4, 1, 0, 0]) / 6
derivative = np.array([0, 1, 0, -1, 0, 0]) / 2
assert_allclose(matrix @ phi, phi)
assert_allclose(matrix @ derivative, derivative / 2, atol=1e-15)


def test_refinement_requires_discrete_wavelet():
with pytest.raises(TypeError, match='discrete wavelet'):
pywt.refinement_matrix(pywt.ContinuousWavelet('mexh'))