removed tophat and bottomhat from filters.rank

[ThomasWalter]

Description

PR in response to discussion #3599 : removed bottomhat and tophat from filters.rank. These filters were named incorrectly. They are effectively calculating internal and external morphological gradients. After discussion with @sciunto and @emmanuelle we came to the conclusion that probably, it does not make so much sense to keep these functions.

Checklist

[It's fine to submit PRs which are a work in progress! But before they are merged, all PRs should provide:]

• Clean style in the spirit of PEP8
• Docstrings for all functions
• Gallery example in ./doc/examples (new features only)
• Benchmark in ./benchmarks, if your changes aren't covered by an
  existing benchmark
• Unit tests

[For detailed information on these and other aspects see scikit-image contribution guidelines]

References

Closes issue #3599

For reviewers

(Don't remove the checklist below.)

• Check that the PR title is short, concise, and will make sense 1 year
  later.
• Check that new functions are imported in corresponding __init__.py.
• Check that new features, API changes, and deprecations are mentioned in
  doc/release/release_dev.rst.
• Consider backporting the PR with @meeseeksdev backport to v0.14.x

[emmanuelle]

If this is approved, doc/release/release_dev.rst will need to be updated as well. I'm not sure we need to use the deprecation process here since I consider these functions to be quite hidden in the library and my gut feeling is that nobody is using them. But of course, not deprecating/warning users is quite brutal, so please comment @scikit-image/core

[jni]

Oh yeah, I don't think we can just remove remove them. Since they are incorrect I don't think we should use deprecation, but rather, try to use import hooks or at least a redefinition of them so that a NotImplementedError or similar can be raised, mentioning that they were removed in 0.14.2/0.15 because they were incorrect, pointing users to how to reimplement the "morphological gradient" (in case they were getting good results with that behaviour), and to use ndimage for tophat/bottomhat. And also maybe point to the relevant discussion in #3599. Yes it will be a long message but a long message is warranted when you pull the rug from under people!

[soupault]

I consider these functions to be quite hidden in the library

They are a part of public API, aren't they? (http://scikit-image.org/docs/dev/api/skimage.filters.rank.html#bottomhat, http://scikit-image.org/docs/dev/api/skimage.filters.rank.html#tophat)

redefinition of them so that a NotImplementedError or similar can be raised, mentioning that they were removed in 0.14.2/0.15 because they were incorrect, pointing users to how to reimplement the "morphological gradient"

👍 on this approach: raise NotImplementedError in 0.15, remove in 0.16. We can include a link to the current implementations (i.e. to GitHub history) into the error messages.

[JDWarner]

Also 👍 on breaking immediately but directing any users to the new location with a brief explanation.

[sciunto]

Postponed to 0.16. @ThomasWalter would mind adding an exception and a task in the todo list please?

[grlee77]

I rebased this to resolve merge conflicts from a recent 3d rank filters PR. Now that 0.18 was released, I think this should be ready to merge if all is green on CI (docstrings since the 0.17 release have indicated these would be removed in 0.19)

[stefanv]

Thanks for your input, everyone!

[stefanv]

And, of course, @ThomasWalter who stuck with this for two years ;)