biquad 0.3__py3-none-any.whl → 0.5__py3-none-any.whl

biquad/__init__.py

@@ -1,55 +1,55 @@
-__version__ = "0.3"
-
-
-from .allpass   import allpass
-from .bandpass  import bandpass
-from .biquad    import biquad
-from .highpass  import highpass
-from .highshelf import highshelf
-from .lowpass   import lowpass
-from .lowshelf  import lowshelf
-from .notch     import notch
-from .peak      import peak
-
-
-def filter(name, sr, **kwargs):
-    """
-    Create a filter instance of the specified filter name.
-
-    Parameters
-    ----------
-    sr : int or float
-        Sample rate in hertz.
-    f : int or float, optional
-        Persistent filter frequency parameter in hertz.
-    q : int or float, optional
-        Persistent filter quality parameter.
-    """
-
-    name = str(name).lower()
-
-    if name in ['allpass', 'all', 'ap', 'apf']:
-        return allpass(sr, **kwargs)
-
-    if name in ['bandpass', 'band', 'bp', 'bpf']:
-        return bandpass(sr, **kwargs)
-
-    if name in ['highpass', 'high', 'hp', 'hpf']:
-        return highpass(sr, **kwargs)
-
-    if name in ['highshelf', 'hs', 'hsf']:
-        return highshelf(sr, **kwargs)
-
-    if name in ['lowpass', 'low', 'lp', 'lpf']:
-        return lowpass(sr, **kwargs)
-
-    if name in ['lowshelf', 'ls', 'lsf']:
-        return lowshelf(sr, **kwargs)
-
-    if name in ['notch', 'nf']:
-        return notch(sr, **kwargs)
-
-    if name in ['peak', 'pf']:
-        return peak(sr, **kwargs)
-
-    return biquad(sr, **kwargs)
+__version__ = "0.5"
+
+
+from .allpass   import allpass
+from .bandpass  import bandpass
+from .biquad    import biquad
+from .highpass  import highpass
+from .highshelf import highshelf
+from .lowpass   import lowpass
+from .lowshelf  import lowshelf
+from .notch     import notch
+from .peak      import peak
+
+
+def filter(name, sr, **kwargs):
+    """
+    Create a filter instance of the specified filter name.
+
+    Parameters
+    ----------
+    sr : int or float
+        Sample rate in hertz.
+    f : int or float, optional
+        Persistent filter frequency parameter in hertz.
+    q : int or float, optional
+        Persistent filter quality parameter.
+    """
+
+    name = str(name).lower()
+
+    if name in ['allpass', 'all', 'ap', 'apf']:
+        return allpass(sr, **kwargs)
+
+    if name in ['bandpass', 'band', 'bp', 'bpf']:
+        return bandpass(sr, **kwargs)
+
+    if name in ['highpass', 'high', 'hp', 'hpf']:
+        return highpass(sr, **kwargs)
+
+    if name in ['highshelf', 'hs', 'hsf']:
+        return highshelf(sr, **kwargs)
+
+    if name in ['lowpass', 'low', 'lp', 'lpf']:
+        return lowpass(sr, **kwargs)
+
+    if name in ['lowshelf', 'ls', 'lsf']:
+        return lowshelf(sr, **kwargs)
+
+    if name in ['notch', 'nf']:
+        return notch(sr, **kwargs)
+
+    if name in ['peak', 'pf']:
+        return peak(sr, **kwargs)
+
+    return biquad(sr, **kwargs)

biquad/allpass.py

@@ -6,7 +6,7 @@ SPDX-License-Identifier: MIT
 Source: https://github.com/jurihock/biquad
 """
 
-from .biquad import biquad, __df1__
+from .biquad import biquad, __df1__, __gain__, __resize__
 
 import numba
 import numpy
@@ -17,7 +17,7 @@ class allpass(biquad):
     Allpass filter (APF).
     """
 
-    def __init__(self, sr, *, f=None, q=1):
+    def __init__(self, sr, f=None, g=0, q=1):
         """
         Create a new filter instance.
 
@@ -27,15 +27,17 @@ class allpass(biquad):
             Sample rate in hertz.
         f : int or float, optional
             Persistent filter frequency parameter in hertz.
+        g : int or float, optional
+            Persistent filter gain parameter in decibel.
         q : int or float, optional
             Persistent filter quality parameter.
         """
 
-        super().__init__(sr=sr, f=f, q=q)
+        super().__init__(sr=sr, f=f, g=g, q=q)
 
-        self.__call__(0, 1) # warmup numba
+        self.__call__(0) # warmup numba
 
-    def __call__(self, x, f=None, q=None):
+    def __call__(self, x, f=None, g=None, q=None):
         """
         Process single or multiple contiguous signal values at once.
 
@@ -45,6 +47,8 @@ class allpass(biquad):
             Filter input data.
         f : scalar or array like, optional
             Instantaneous filter frequency parameter in hertz.
+        g : scalar or array like, optional
+            Instantaneous filter gain parameter in decibel.
         q : scalar or array like, optional
             Instantaneous filter quality parameter.
 
@@ -62,21 +66,23 @@ class allpass(biquad):
         x = numpy.atleast_1d(x)
         y = numpy.zeros(x.shape, x.dtype)
 
-        f = numpy.atleast_1d(self.f if f is None else f)
-        q = numpy.atleast_1d(self.q if q is None else q)
-
-        f = numpy.resize(f, x.shape)
-        q = numpy.resize(q, x.shape)
+        f = __resize__(self.f if f is None else f, x.shape)
+        g = __resize__(self.g if g is None else __gain__(g), x.shape)
+        q = __resize__(self.q if q is None else q, x.shape)
 
         sr = self.sr
 
-        self.__filter__(ba, xy, x, y, f, q, sr)
+        self.__filter__(ba, xy, x, y, f, g, q, sr)
+
+        self.f = f[-1]
+        self.g = g[-1]
+        self.q = q[-1]
 
         return y[0] if scalar else y
 
     @staticmethod
     @numba.jit(nopython=True, fastmath=True)
-    def __filter__(ba, xy, x, y, f, q, sr):
+    def __filter__(ba, xy, x, y, f, g, q, sr):
 
         rs = 2 * numpy.pi / sr
 
@@ -87,18 +93,18 @@ class allpass(biquad):
             cosw = numpy.cos(w)
             sinw = numpy.sin(w)
 
-            c = -(2 * cosw)
-            p = sinw / (2 * q[i])
+            alpha = sinw / (+2 * q[i])
+            beta  = cosw * (-2)
 
             # update b
-            ba[0, 0] = 1 - p
-            ba[0, 1] =     c
-            ba[0, 2] = 1 + p
+            ba[0, 0] = 1 - alpha
+            ba[0, 1] =     beta
+            ba[0, 2] = 1 + alpha
 
             # update a
-            ba[1, 0] = 1 + p
-            ba[1, 1] =     c
-            ba[1, 2] = 1 - p
+            ba[1, 0] = 1 + alpha
+            ba[1, 1] =     beta
+            ba[1, 2] = 1 - alpha
 
             # update y
-            __df1__(ba, xy, x, y, i)
+            __df1__(g[i], ba, xy, x, y, i)

biquad/bandpass.py

@@ -6,7 +6,7 @@ SPDX-License-Identifier: MIT
 Source: https://github.com/jurihock/biquad
 """
 
-from .biquad import biquad, __df1__
+from .biquad import biquad, __df1__, __gain__, __resize__
 
 import numba
 import numpy
@@ -17,7 +17,7 @@ class bandpass(biquad):
     Bandpass filter (BPF).
     """
 
-    def __init__(self, sr, gain='skirt', *, f=None, q=0.7071):
+    def __init__(self, sr, f=None, g=0, q=0.7071, *, mode='peak'):
         """
         Create a new filter instance.
 
@@ -25,23 +25,25 @@ class bandpass(biquad):
         ----------
         sr : int or float
             Sample rate in hertz.
-        gain : str, skirt or peak, optional
-            Choice between constant skirt gain or constant 0 dB peak gain.
         f : int or float, optional
             Persistent filter frequency parameter in hertz.
+        g : int or float, optional
+            Persistent filter gain parameter in decibel.
         q : int or float, optional
             Persistent filter quality parameter.
+        mode : str, peak or skirt, optional
+            Choice between constant 0 dB peak gain or constant skirt gain.
         """
 
-        super().__init__(sr=sr, f=f, q=q)
+        super().__init__(sr=sr, f=f, g=g, q=q)
 
-        assert gain in ['skirt', 'peak']
+        assert mode in ['peak', 'skirt']
 
-        self.gain = gain
+        self.mode = mode
 
-        self.__call__(0, 1) # warmup numba
+        self.__call__(0) # warmup numba
 
-    def __call__(self, x, f=None, q=None):
+    def __call__(self, x, f=None, g=None, q=None):
         """
         Process single or multiple contiguous signal values at once.
 
@@ -51,6 +53,8 @@ class bandpass(biquad):
             Filter input data.
         f : scalar or array like, optional
             Instantaneous filter frequency parameter in hertz.
+        g : scalar or array like, optional
+            Instantaneous filter gain parameter in decibel.
         q : scalar or array like, optional
             Instantaneous filter quality parameter.
 
@@ -68,25 +72,27 @@ class bandpass(biquad):
         x = numpy.atleast_1d(x)
         y = numpy.zeros(x.shape, x.dtype)
 
-        f = numpy.atleast_1d(self.f if f is None else f)
-        q = numpy.atleast_1d(self.q if q is None else q)
-
-        f = numpy.resize(f, x.shape)
-        q = numpy.resize(q, x.shape)
+        f = __resize__(self.f if f is None else f, x.shape)
+        g = __resize__(self.g if g is None else __gain__(g), x.shape)
+        q = __resize__(self.q if q is None else q, x.shape)
 
         sr = self.sr
-        gain = self.gain
+        mode = self.mode
+
+        self.__filter__(ba, xy, x, y, f, g, q, sr, mode)
 
-        self.__filter__(ba, xy, x, y, f, q, sr, gain)
+        self.f = f[-1]
+        self.g = g[-1]
+        self.q = q[-1]
 
         return y[0] if scalar else y
 
     @staticmethod
     @numba.jit(nopython=True, fastmath=True)
-    def __filter__(ba, xy, x, y, f, q, sr, gain):
+    def __filter__(ba, xy, x, y, f, g, q, sr, mode):
 
         rs = 2 * numpy.pi / sr
-        skirt = gain == 'skirt'
+        skirt = mode == 'skirt'
 
         for i in range(x.size):
 
@@ -95,19 +101,19 @@ class bandpass(biquad):
             cosw = numpy.cos(w)
             sinw = numpy.sin(w)
 
-            c = -(2 * cosw)
-            p = sinw / (2 * q[i])
-            g = sinw / 2 if skirt else p
+            alpha = sinw / (+2 * q[i])
+            beta  = cosw * (-2)
+            gamma = sinw / (+2) if skirt else alpha
 
             # update b
-            ba[0, 0] = +g
+            ba[0, 0] = +gamma
             ba[0, 1] =  0
-            ba[0, 2] = -g
+            ba[0, 2] = -gamma
 
             # update a
-            ba[1, 0] = 1 + p
-            ba[1, 1] =     c
-            ba[1, 2] = 1 - p
+            ba[1, 0] = 1 + alpha
+            ba[1, 1] =     beta
+            ba[1, 2] = 1 - alpha
 
             # update y
-            __df1__(ba, xy, x, y, i)
+            __df1__(g[i], ba, xy, x, y, i)

biquad/biquad.py

@@ -6,17 +6,15 @@ SPDX-License-Identifier: MIT
 Source: https://github.com/jurihock/biquad
 """
 
-from .plot import plot
-
 import numba
 import numpy
 
 
 @numba.jit(nopython=True, fastmath=True)
-def __df1__(ba, xy, x, y, i):
+def __df1__(g, ba, xy, x, y, i):
     """
-    Computes filter output y[i] based on filter input x[i]
-    as well as specified filter coeffs ba and delay line xy,
+    Compute filter output y[i] based on filter input x[i]
+    as well as specified filter gain g, coeffs ba and delay line xy,
     according to the Direct Form 1.
     """
 
@@ -31,37 +29,67 @@ def __df1__(ba, xy, x, y, i):
     # update x
     xy[0, 0] = x[i]
 
+    # compute intermediate results b*x and a*y
+    bx = ba[0, 0] * xy[0, 0] + ba[0, 1] * xy[0, 1] + ba[0, 2] * xy[0, 2]
+    ay =                       ba[1, 1] * xy[1, 1] + ba[1, 2] * xy[1, 2]
+
     # update y
-    xy[1, 0] = (ba[0, 0] * xy[0, 0]  + \
-                ba[0, 1] * xy[0, 1]  + \
-                ba[0, 2] * xy[0, 2]  - \
-                ba[1, 1] * xy[1, 1]  - \
-                ba[1, 2] * xy[1, 2]) / ba[1, 0]
+    xy[1, 0] = (bx * g - ay) / ba[1, 0]
 
     # return y
     y[i] = xy[1, 0]
 
 
-class biquad:
+def __gain__(x, divisor=20):
     """
-    Biquad filter base class.
+    Convert the specified decibel gain to the linear gain.
     """
 
-    ba = numpy.array([[1, 0, 0], [1, 0, 0]], float)
+    if numpy.isscalar(x):
+
+        y = x / divisor
+        y = 10 ** y
+
+    else:
+
+        y = numpy.atleast_1d(x) / divisor
+        numpy.power(10, y, out=y)
+
+    return y
+
+
+def __resize__(x, shape):
     """
-    Biquad filter coefficient matrix of shape (2, 3):
-        - ba[0] holds b coefficients
-        - ba[1] holds a coefficients
+    Resize the specified value to the ndarray of desired shape.
     """
 
-    xy = numpy.array([[0, 0, 0], [0, 0, 0]], float)
+    if numpy.isscalar(x):
+
+        y = numpy.full(shape, x)
+
+    else:
+
+        x = numpy.atleast_1d(x)
+        y = numpy.resize(x, shape)
+
+    return y
+
+
+class biquad:
     """
-    Biquad filter delay line matrix of shape (2, 3):
-        - xy[0] holds input values
-        - xy[0] holds output values
+    Biquad filter base class.
+
+    Parameters
+    ----------
+    ba : Biquad filter coefficient matrix of shape (2, 3) excl. gain factor:
+         - ba[0] holds b coefficients
+         - ba[1] holds a coefficients
+    xy : Biquad filter delay line matrix of shape (2, 3):
+         - xy[0] holds input values
+         - xy[1] holds output values
     """
 
-    def __init__(self, sr, *, f=None, q=None):
+    def __init__(self, sr, f=None, g=None, q=None):
         """
         Create a new filter instance.
 
@@ -71,26 +99,34 @@ class biquad:
             Sample rate in hertz.
         f : int or float, optional
             Persistent filter frequency parameter in hertz.
+        g : int or float, optional
+            Persistent filter gain parameter in decibel.
         q : int or float, optional
             Persistent filter quality parameter.
         """
 
         assert (sr is not None) and (numpy.isscalar(sr) and numpy.isreal(sr))
         assert (f  is     None) or  (numpy.isscalar(f)  and numpy.isreal(f))
+        assert (g  is     None) or  (numpy.isscalar(g)  and numpy.isreal(g))
         assert (q  is     None) or  (numpy.isscalar(q)  and numpy.isreal(q))
 
         self.sr = sr
-        self.f  = f
-        self.q  = q
+        self.f  = (sr / 4) if f is None else f
+        self.g  = __gain__(0 if g is None else g)
+        self.q  = 1 if q is None else q
+
+        self.ba = numpy.array([[1, 0, 0], [1, 0, 0]], float)
+        self.xy = numpy.array([[0, 0, 0], [0, 0, 0]], float)
 
         # warmup numba
+        g  = self.g
         ba = self.ba
         xy = self.xy
-        x = numpy.zeros(1, float)
-        y = numpy.zeros(x.shape, x.dtype)
-        __df1__(ba, xy, x, y, 0)
+        x  = numpy.zeros(1, float)
+        y  = numpy.zeros(x.shape, x.dtype)
+        __df1__(g, ba, xy, x, y, 0)
 
-    def __call__(self, x, f=None, q=None):
+    def __call__(self, x, f=None, g=None, q=None):
         """
         Process single or multiple contiguous signal values at once.
 
@@ -100,6 +136,8 @@ class biquad:
             Filter input data.
         f : scalar or array like, optional
             Instantaneous filter frequency parameter in hertz.
+        g : scalar or array like, optional
+            Instantaneous filter gain parameter in decibel.
         q : scalar or array like, optional
             Instantaneous filter quality parameter.
 
@@ -117,19 +155,27 @@ class biquad:
         x = numpy.atleast_1d(x)
         y = numpy.zeros(x.shape, x.dtype)
 
-        self.__filter__(ba, xy, x, y)
+        f = __resize__(self.f if f is None else f, x.shape)
+        g = __resize__(self.g if g is None else __gain__(g), x.shape)
+        q = __resize__(self.q if q is None else q, x.shape)
+
+        self.__filter__(ba, xy, x, y, g)
+
+        self.f = f[-1]
+        self.g = g[-1]
+        self.q = q[-1]
 
         return y[0] if scalar else y
 
     @staticmethod
     @numba.jit(nopython=True, fastmath=True)
-    def __filter__(ba, xy, x, y):
+    def __filter__(ba, xy, x, y, g):
 
         for i in range(x.size):
 
-            __df1__(ba, xy, x, y, i)
+            __df1__(g[i], ba, xy, x, y, i)
 
-    def response(self, norm=False, log=False):
+    def response(self, *, norm=False, log=False):
         """
         Returns frequency and phase response of the transfer function given by the ba coefficients.
 
@@ -154,6 +200,8 @@ class biquad:
 
         (b, a), sr = self.ba, self.sr
 
+        b *= self.g
+
         n = int(sr / 2)
 
         # compute frequencies from 0 to pi or sr/2 but excluding the Nyquist frequency
@@ -175,12 +223,46 @@ class biquad:
 
         return w, h
 
-    def plot(self):
+    def plot(self, *, log=False):
         """
-        Returns a filter response plotting wrapper to
-        easily create the frequency or phase response plots.
+        Creates filter frequency and phase response plot.
+
+        Parameters
+        ----------
+        log : bool, optional
+            Option whether to express frequency values logarithmically.
         """
 
+        import matplotlib.pyplot as pyplot
+
         w, h = self.response()
 
-        return plot(w, h)
+        with numpy.errstate(divide='ignore', invalid='ignore'):
+            habs = 20 * numpy.log10(numpy.abs(h))
+
+        harg = numpy.angle(h)
+
+        pyplot.plot(w, habs, color='b', alpha=0.9)
+        axis1 = pyplot.gca()
+        axis2 = axis1.twinx()
+        axis2.plot(w, harg, color='g', alpha=0.9)
+
+        axis1.set_xlabel('Hz')
+        axis1.set_ylabel('dB',  color='b')
+        axis2.set_ylabel('rad', color='g')
+
+        habsmin = numpy.min(habs[numpy.isfinite(habs)])
+        habsmax = numpy.max(habs[numpy.isfinite(habs)])
+
+        habsmin = numpy.minimum(habsmin, -100)
+        habsmax = numpy.maximum(habsmax, +10)
+
+        hargmin = -numpy.pi
+        hargmax = +numpy.pi
+
+        axis1.set_ylim((habsmin * 1.1, habsmax * 1.1))
+        axis2.set_ylim((hargmin * 1.1, hargmax * 1.1))
+
+        if log: axis1.set_xscale('log')
+
+        return pyplot

biquad/highpass.py

@@ -6,7 +6,7 @@ SPDX-License-Identifier: MIT
 Source: https://github.com/jurihock/biquad
 """
 
-from .biquad import biquad, __df1__
+from .biquad import biquad, __df1__, __gain__, __resize__
 
 import numba
 import numpy
@@ -17,7 +17,7 @@ class highpass(biquad):
     Highpass filter (HPF).
     """
 
-    def __init__(self, sr, *, f=None, q=0.7071):
+    def __init__(self, sr, f=None, g=0, q=0.7071):
         """
         Create a new filter instance.
 
@@ -27,15 +27,17 @@ class highpass(biquad):
             Sample rate in hertz.
         f : int or float, optional
             Persistent filter frequency parameter in hertz.
+        g : int or float, optional
+            Persistent filter gain parameter in decibel.
         q : int or float, optional
             Persistent filter quality parameter.
         """
 
-        super().__init__(sr=sr, f=f, q=q)
+        super().__init__(sr=sr, f=f, g=g, q=q)
 
-        self.__call__(0, 1) # warmup numba
+        self.__call__(0) # warmup numba
 
-    def __call__(self, x, f=None, q=None):
+    def __call__(self, x, f=None, g=None, q=None):
         """
         Process single or multiple contiguous signal values at once.
 
@@ -45,6 +47,8 @@ class highpass(biquad):
             Filter input data.
         f : scalar or array like, optional
             Instantaneous filter frequency parameter in hertz.
+        g : scalar or array like, optional
+            Instantaneous filter gain parameter in decibel.
         q : scalar or array like, optional
             Instantaneous filter quality parameter.
 
@@ -62,21 +66,23 @@ class highpass(biquad):
         x = numpy.atleast_1d(x)
         y = numpy.zeros(x.shape, x.dtype)
 
-        f = numpy.atleast_1d(self.f if f is None else f)
-        q = numpy.atleast_1d(self.q if q is None else q)
-
-        f = numpy.resize(f, x.shape)
-        q = numpy.resize(q, x.shape)
+        f = __resize__(self.f if f is None else f, x.shape)
+        g = __resize__(self.g if g is None else __gain__(g), x.shape)
+        q = __resize__(self.q if q is None else q, x.shape)
 
         sr = self.sr
 
-        self.__filter__(ba, xy, x, y, f, q, sr)
+        self.__filter__(ba, xy, x, y, f, g, q, sr)
+
+        self.f = f[-1]
+        self.g = g[-1]
+        self.q = q[-1]
 
         return y[0] if scalar else y
 
     @staticmethod
     @numba.jit(nopython=True, fastmath=True)
-    def __filter__(ba, xy, x, y, f, q, sr):
+    def __filter__(ba, xy, x, y, f, g, q, sr):
 
         rs = 2 * numpy.pi / sr
 
@@ -87,8 +93,8 @@ class highpass(biquad):
             cosw = numpy.cos(w)
             sinw = numpy.sin(w)
 
-            c = -(2 * cosw)
-            p = sinw / (2 * q[i])
+            alpha = sinw / (+2 * q[i])
+            beta  = cosw * (-2)
 
             # update b
             ba[0, 1] = -(1 + cosw)
@@ -96,9 +102,9 @@ class highpass(biquad):
             ba[0, 0] = ba[0, 2]
 
             # update a
-            ba[1, 0] = 1 + p
-            ba[1, 1] =     c
-            ba[1, 2] = 1 - p
+            ba[1, 0] = 1 + alpha
+            ba[1, 1] =     beta
+            ba[1, 2] = 1 - alpha
 
             # update y
-            __df1__(ba, xy, x, y, i)
+            __df1__(g[i], ba, xy, x, y, i)