Librosa: logamplitude function examples don't use the logamplitude function

[ericdrobinson]

Description

Examples in the documentation for the librosa.core.logamplitude() function do not actually use librosa.core.logamplitude().

Steps/Code to Reproduce

Check the examples on this documentation page: https://librosa.github.io/librosa/generated/librosa.core.logamplitude.html

Expected Results

The examples show the function in action.

Actual Results

The function is not used in the example code.

Versions

0.5.0+

Notes

I understand that the function has been deprecated. Regardless, examples should still show how it's used (0.4 versions did have examples...).

[bmcfee]

This is because the function was renamed to power_to_db in 0.5, and we keep backwards compatibility (for now) by making a deprecation alias here. Calls to logamplitude are thus translated automatically to use the new function name power_to_db.

The example code does use the new naming (so that docs are forward-compatible), but it is functionally identical to the same code using the old name.

I'm not sure that there's a good solution to this issue, other than more clearly documenting that the two are identical. I don't want to have two copies of the function around just for the sake of having slightly different docstring examples, and it's probably overkill to try adding example parsing/substitution to the deprectation move decorator.

Since this is by design a short-term problem, I'm inclined to leave it as is.

[ericdrobinson]

Got it. Thanks so much for the explanation!

I'm not sure that there's a good solution to this issue, other than more clearly documenting that the two are identical. I don't want to have two copies of the function around just for the sake of having slightly different docstring examples, and it's probably overkill to try adding example parsing/substitution to the deprectation move decorator.

I hear you there. Definitely sounds like overkill. I'd missed the fact that it was simply an alias.

Might I suggest that the Warning Box be implemented at the function level for deprecated functions? You could place an explanation of what's going on in (as you did here) in the Warning box... I am, of course, speaking of the "Warning Box" that already exists for deprecated parameters (there's an example in the logamplitude documentation page).

Since this is by design a short-term problem, I'm inclined to leave it as is.

I think this is a reasonable assessment!

[bmcfee]

You could place an explanation of what's going on in (as you did here) in the Warning box...

Yeah. I think it wouldn't be too hard to use functools to inject a warning box into the docstring of wrapped functions. I won't have time to do this in the immediate future, but it would be a good PR for newbies that only requires python knowledge and no audio/DSP background.

[bmcfee]

Merging #627 resolves this by removing logamplitude throughout the package.