BUG: iircomb peaking behavior doesn't match documentation

Describe your issue.

The second example in the documentation for signal.iircomb says:

f0 = 250.0  # Frequency to be retained (Hz)

But this is not the frequency to be retained, it’s the frequency that is cut:

Likewise the parameter w0 says:

Frequency to attenuate (notching) or boost (peaking).

which is incorrect. With ftype='peak', 250 Hz is not boosted.

Comb filters do support peaking and notching at both types of frequencies, by varying the sign of the last coefficients, and I would like to support all four configurations in SciPy:

b = [0.0498, 0, 0, 0, -0.0498], a = [1, 0, 0, 0, 0.9]

 b = [0.0498, 0, 0, 0, 0.0498], a = [1, 0, 0, 0, -0.9]

b = [0.95, 0, 0, 0, -0.95], a = [1, 0, 0, 0, -0.9]

b = [0.95, 0, 0, 0, 0.95], a = [1, 0, 0, 0, 0.9]

However, I’m not sure what the best interface is. I’m not sure if this counts as a bug in the documentation or a bug in the code.

• If we consider it a bug in the code, then we could change the functionality to match the documentation, so that peaking and notching both occur on the frequency specified (which seems more natural to me), and then add another parameter (shift? invert?) that shifts to the “between frequencies” when True.
• If we consider the documentation to be the bug, then the behavior is kind of strange, but I guess we’d add some other parameter to get the other two behaviors (notching between specified frequency, peaking at specified frequency).
• Or there could be four ftype options for the two notching and two peaking variants? With peak and notch kept undocumented for backwards compatibility? But I don’t know what to call the other four options. peak_at and peak_between or something?

Reproducing Code Example

fs = 1000.0  # Sample frequency (Hz)
f0 = 250.0  # Frequency to be retained (Hz)
Q = 30.0  # Quality factor

# Design peaking filter
b, a = signal.iircomb(f0, Q, ftype='peak', fs=fs)

# Frequency response
freq, h = signal.freqz(b, a, fs=fs)
response = abs(h)

# To avoid divide by zero when graphing
response[response == 0] = 1e-20

# Plot
fig, ax = plt.subplots(2, 1, figsize=(8, 6))
ax[0].plot(freq, 20*np.log10(np.maximum(abs(h), 1e-5)), color='blue')
ax[0].set_title("Frequency Response")
ax[0].set_ylabel("Amplitude (dB)", color='blue')
ax[0].set_xlim([0, 500])
ax[0].set_ylim([-80, 10])
ax[0].grid()
ax[1].plot(freq, np.unwrap(np.angle(h))*180/np.pi, color='green')
ax[1].set_ylabel("Angle (degrees)", color='green')
ax[1].set_xlabel("Frequency (Hz)")
ax[1].set_xlim([0, 500])
ax[1].set_yticks([-90, -60, -30, 0, 30, 60, 90])
ax[1].set_ylim([-90, 90])
ax[1].grid()
plt.show()

Error message

None

SciPy/NumPy/Python version information

1.7.3 1.20.3 sys.version_info(major=3, minor=7, micro=13, releaselevel=‘final’, serial=0)

[larsoner]

I guess this could be a separate parameter? Or a different ftype maybe?

At least for the FIR case it’s a bit weird to get the behavior from a function named iircomb, I’d be tempted to make a fircomb. But if we can get all these behaviors from a single function I can live with it being part of iircomb even if the impulse response is finite.

Can you think of a clean API from scratch that would work for the Wikipedia cases? Maybe we should start from there and then decide if we can make it fit into iircomb somehow, or if we should make a separate function / separate functions.

[larsoner]

If we consider the documentation to be the bug, then the behavior is kind of strange, but I guess we’d add some other parameter to get the other two behaviors (notching between specified frequency, peaking at specified frequency).

Okay thinking about this option more, how about following firwin a bit and add pass_zero=False:

iircomb(w0, Q, ftype='notch', fs=2.0, pass_zero=False):

Then it’s clear(er) that for either ftype, by default, zero will be notched – and hence f0 and its multiples will be notched, too. If you pass pass_zero=True, (f0 * n)/ 2. will be notched instead.

It’s not as pretty as maybe we’d like, but it’s at least internally somewhat consistent (with firwin) and avoids any deprecation…