diff --git a/doc/source/ref/other-functions.rst b/doc/source/ref/other-functions.rst index 414f1203..8d037533 100644 --- a/doc/source/ref/other-functions.rst +++ b/doc/source/ref/other-functions.rst @@ -7,6 +7,12 @@ Other functions =============== +Discrete scaling function refinement +------------------------------------ + +.. autofunction:: refinement_matrix + + Integrating wavelet functions ----------------------------- diff --git a/pywt/_functions.py b/pywt/_functions.py index b2826d81..a1ed8fc2 100644 --- a/pywt/_functions.py +++ b/pywt/_functions.py @@ -17,7 +17,7 @@ __all__ = ["integrate_wavelet", "central_frequency", "scale2frequency", "frequency2scale", "qmf", - "orthogonal_filter_bank", + "orthogonal_filter_bank", "refinement_matrix", "intwave", "centrfrq", "scal2frq", "orthfilt"] @@ -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 diff --git a/pywt/tests/test_refinement_matrix.py b/pywt/tests/test_refinement_matrix.py new file mode 100644 index 00000000..a83999b0 --- /dev/null +++ b/pywt/tests/test_refinement_matrix.py @@ -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'))