specshow: warn when frequency axis seems implausible

Describe the bug

librosa.display.specshow malfunctions for y_axis=cqt_hz. If I double the number of CQT bins in the example at librosa.display.specshow, then the y axis blows up to incorrect Hz values. If I triple it then they blow up to infinity

Reproducible example

import matplotlib.pyplot as plt
y, sr = librosa.load(librosa.util.example_audio_file())
plt.figure(figsize=(12, 8))

# Calculate CQT with twice the default frequency resolution
resolution = 2
CQT = librosa.cqt(y, sr=sr, n_bins=84*resolution, bins_per_octave=12*resolution)
CQT = librosa.amplitude_to_db(np.abs(CQT), ref=np.max)

# CQT note as y axis
plt.subplot(4, 2, 3)
librosa.display.specshow(CQT, y_axis='cqt_note')
plt.colorbar(format='%+2.0f dB')
plt.title('Constant-Q power spectrogram (note)')

# CQT Hz as y axis
plt.subplot(4, 2, 4)
librosa.display.specshow(CQT, y_axis='cqt_hz')
plt.colorbar(format='%+2.0f dB')
plt.title('Constant-Q power spectrogram (Hz)')

Outputs:

• resolution = 1 (the example in the docs)

• resolution = 2

• resolution = 3

/usr/local/Caskroom/miniconda/base/envs/myproject/lib/python3.6/site-packages/librosa/core/time_frequency.py in midi_to_note(midi, octave, cents)
    601                 'G#', 'A', 'A#', 'B']
    602 
--> 603     note_num = int(np.round(midi))
    604     note_cents = int(100 * np.around(midi - note_num, 2))
    605 

OverflowError: cannot convert float infinity to integer

Software versions

Darwin-19.4.0-x86_64-i386-64bit
Python 3.7.7 (default, Mar 10 2020, 15:43:33) 
[Clang 11.0.0 (clang-1100.0.33.17)]
NumPy 1.18.4
SciPy 1.4.1
librosa 0.7.2
INSTALLED VERSIONS
------------------
python: 3.7.7 (default, Mar 10 2020, 15:43:33) 
[Clang 11.0.0 (clang-1100.0.33.17)]

librosa: 0.7.2

audioread: 2.1.8
numpy: 1.18.4
scipy: 1.4.1
sklearn: 0.23.1
joblib: 0.15.1
decorator: 4.4.2
six: 1.15.0
soundfile: 0.10.3
resampy: 0.2.2
numba: 0.49.1

numpydoc: None
sphinx: None
sphinx_rtd_theme: None
sphinxcontrib.versioning: None
sphinx-gallery: None
pytest: 5.4.2
pytest-mpl: None
pytest-cov: None
matplotlib: 3.2.1
presets: None

[bmcfee]

a simple note in the documentation for librosa.display.specshow would have helped.

Sure, I think that + a warning if the frequency range exceeds Nyquist would be easy and improve usability.

I was actually thinking a solution could be to use classes.

We’re not going to classes; Gael Varoquaux’s scipy 2017 keynote lays out many good arguments for why (and is full of good advice overall).

[JulianFerry]

I’m not so sure about this specific idea, but more generally I think we can do something useful here. Eg: if the chosen parameters and input data would produce a frequency range that exceeds nyquist, that’s a good sign that something is wrong and we should warn about it. It’s not foolproof, but it would catch really obvious errors.

I didn’t notice until now that the function uses a sampling rate - I agree with nyquist.

On the non-technical side, do you think it would help to have a documentation page that lists common pitfalls (like not carrying over analysis parameters)? I usually find these things to be less helpful than fixing things at the API level, but not all things can (or should) be fixed at the API level IMO.

It could be useful… but I agree with you about making the API as straightforward as possible, or the existing docs. Here for example, a simple note in the documentation for librosa.display.specshow would have helped. Something like:

y_axis:None or str
...
    Frequency types:
    ...

    All frequency types are plotted in units of Hz.
    For Mel and CQT scales, the parameters `fmin`, `fmax` and `hop_length`
    should be identical to those used to generate the spectrogram.

the data structures we use (vanilla numpy ndarrays) provide no means to carry them along for the ride

I was actually thinking a solution could be to use classes. E.g.

• One for Spectrogram, which would track things like the sampling rate, fmin and fmax (in the case of Mel and CQT), which could have its own .plot() method with much fewer parameters.
• Add an Audio class with its own methods to display and pitch shift etc…
• Audio and Spectrogram methods would generally return an Audio or Spectrogram object

But this would be a major API overhaul which would be quite a bit of work and may be frustrating for existing users. I’ve also only just started using librosa so I don’t want to crash the party and request a complete do-over haha