`scipy.signal._filter_design:group_delay`

source: /scipy/signal/_filter_design.py :695

Signature

   def     group_delay (    system    ,    w    =  512   ,    whole    =  False   ,    fs    =  6.283185307179586     )

Summary

Compute the group delay of a digital filter.

Extended Summary

The group delay measures by how many samples amplitude envelopes of various spectral components of a signal are delayed by a filter. It is formally defined as the derivative of continuous (unwrapped) phase

          d        jw
D(w) = - -- arg H(e)
         dw

Parameters

system : tuple of array_like (b, a)

Numerator and denominator coefficients of a filter transfer function.

w : {None, int, array_like}, optional

If a single integer, then compute at that many frequencies (default is N=512).

If an array_like, compute the delay at the frequencies given. These are in the same units as fs.

whole : bool, optional

Normally, frequencies are computed from 0 to the Nyquist frequency, fs/2 (upper-half of unit-circle). If whole is True, compute frequencies from 0 to fs. Ignored if w is array_like.

fs : float, optional

The sampling frequency of the digital system. Defaults to 2*pi radians/sample (so w is from 0 to pi).

Returns

w : ndarray: The frequencies at which group delay was computed, in the same units as fs. By default, w is normalized to the range [0, pi) (radians/sample).
gd : ndarray: The group delay.

Notes

The similar function in MATLAB is called grpdelay.

If the transfer function $H (z)$ has zeros or poles on the unit circle, the group delay at corresponding frequencies is undefined. When such a case arises the warning is raised and the group delay is set to 0 at those frequencies.

For the details of numerical computation of the group delay refer to ^[1] or ^[2].

Array API Standard Support

group_delay has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable SCIPY_ARRAY_API=1 and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

====================  ====================  ====================
Library               CPU                   GPU
====================  ====================  ====================
NumPy                 ✅                     n/a                 
CuPy                  n/a                   ✅                   
PyTorch               ✅                     ⛔                   
JAX                   ⚠️ no JIT             ⛔                   
Dask                  ⚠️ computes graph     n/a                 
====================  ====================  ====================

See dev-arrayapi for more information.

Examples

from scipy import signal
b, a = signal.iirdesign(0.1, 0.3, 5, 50, ftype='cheby1')
w, gd = signal.group_delay((b, a))

✓

import matplotlib.pyplot as plt

✓

plt.title('Digital filter group delay')
plt.plot(w, gd)
plt.ylabel('Group delay [samples]')
plt.xlabel('Frequency [rad/sample]')

✗

plt.show()

✓

Aliases

scipy.signal.group_delay