Source code for ezmsg.sigproc.util.minphase

"""Minimum-phase conversion of FIR kernels, real or complex."""

import numpy as np
import numpy.typing as npt
import scipy.signal as sps

from ..spectrum import OptionsEnum


[docs] class MinPhaseMode(OptionsEnum): """How to convert a linear-phase FIR kernel to minimum phase.""" NONE = "No kernel modification" HILBERT = ( "Hilbert Method; designed to be used with equiripple filters (e.g., from remez) with unity or zero gain regions" ) HOMOMORPHIC = ( "Works best with filters with an odd number of taps, and the resulting minimum phase filter " "will have a magnitude response that approximates the square root of the original filter’s " "magnitude response using half the number of taps" ) HOMOMORPHICFULL = "Like HOMOMORPHIC, but uses the full number of taps and same magnitude"
def _complex_homomorphic(h: npt.NDArray, half: bool) -> npt.NDArray: """Homomorphic minimum phase for a complex kernel, mirroring scipy's real-only routine. The log-magnitude spectrum is real even when ``h`` is complex, so its cepstrum is Hermitian and the usual fold onto positive quefrencies still yields the causal, minimum-phase cepstrum. Unlike the real case the result is kept complex. """ n = h.shape[0] n_fft = 2 ** int(np.ceil(np.log2(2 * (n - 1) / 0.01))) # scipy.signal.minimum_phase default mag = np.abs(np.fft.fft(h, n_fft)) log_mag = np.log(np.maximum(mag, 1e-7 * mag.max())) if half: log_mag *= 0.5 win = np.zeros(n_fft) win[0] = 1 win[1 : n_fft // 2] = 2 win[n_fft // 2] = 1 # n_fft is a power of 2, so this is the Nyquist bin h_min = np.fft.ifft(np.exp(np.fft.fft(np.fft.ifft(log_mag) * win))) return h_min[: (n + 1) // 2 if half else n]
[docs] def min_phase_kernel(h: npt.NDArray, mode: MinPhaseMode) -> npt.NDArray: """Convert a linear-phase FIR kernel to its minimum-phase equivalent. Real kernels go to :func:`scipy.signal.minimum_phase`. Complex kernels (e.g. analytic wavelets) use an equivalent homomorphic routine; the Hilbert method has no complex counterpart and raises. Args: h: 1-D FIR kernel. mode: HILBERT and HOMOMORPHIC return ``(len(h) + 1) // 2`` taps with approximately the square root of the original magnitude response; HOMOMORPHICFULL returns ``len(h)`` taps with approximately the original magnitude response; NONE returns ``h`` unchanged. Returns: The converted kernel. """ if mode == MinPhaseMode.NONE: return h if np.iscomplexobj(h): if mode == MinPhaseMode.HILBERT: raise ValueError( "MinPhaseMode.HILBERT does not support complex kernels; " "use MinPhaseMode.HOMOMORPHIC or MinPhaseMode.HOMOMORPHICFULL." ) if h.ndim != 1 or h.shape[0] <= 2: raise ValueError("h must be 1-D and at least 3 samples long") return _complex_homomorphic(h, half=mode == MinPhaseMode.HOMOMORPHIC) if mode == MinPhaseMode.HILBERT: return sps.minimum_phase(h, method="hilbert") return sps.minimum_phase(h, method="homomorphic", half=mode == MinPhaseMode.HOMOMORPHIC)
[docs] def is_linear_phase(h: npt.NDArray) -> bool: """Whether a 1-D FIR kernel is (generalized) linear phase. True for symmetric and antisymmetric real kernels and for conjugate-symmetric or conjugate-antisymmetric complex ones, i.e. ``h == ±conj(h[::-1])``. """ h = np.asarray(h) h_rev = np.conj(h[::-1]) atol = 1e-9 * float(np.max(np.abs(h), initial=0.0)) return bool(np.allclose(h, h_rev, rtol=0, atol=atol) or np.allclose(h, -h_rev, rtol=0, atol=atol))
[docs] def kernel_delay(h: npt.NDArray) -> float: """Delay of a 1-D FIR kernel, in samples. Exactly ``(len(h) - 1) / 2`` for a linear-phase kernel (see :func:`is_linear_phase`). Otherwise the group delay at the frequency where ``|H|`` peaks -- the envelope delay at band centre, which is an approximation because the delay varies with frequency. """ h = np.asarray(h) if is_linear_phase(h): return (h.shape[0] - 1) / 2 whole = np.iscomplexobj(h) # a complex kernel's response is not mirrored about DC n_freqs = max(1024, 8 * h.shape[0]) w, resp = sps.freqz(h, worN=n_freqs, whole=whole) _, gd = sps.group_delay((h, 1), w=[w[np.argmax(np.abs(resp))]], whole=whole) return float(gd[0])