Refactor api

[kahaaga]

What is this PR?

A major refactoring of the codebase and documentation, as discussed in #81 and various PRs leading up to that.

Which changes are included?

There are a lot of changes in terms of file count, but few actual changes to internal code. The easiest way to get an overview is to build the docs locally and have a look.

• Functions have been renamed.
• Convenience functions for Shannon entropy methods have been added.
• An attempt at a coherent documentation, following discussions in Complexity measure API #81
• A section on "Complexity measures" in the documentation, which prepares for Sample entropy #71, Approximate entropy #72, and Walkthrough entropy #70.

If we go for the API in this PR, I can also easily fix #84

[codecov]

Codecov Report

Merging #89 (aace207) into main (e093e13) will decrease coverage by 6.32%.
The diff coverage is 48.25%.

@@            Coverage Diff             @@
##             main      #89      +/-   ##
==========================================
- Coverage   77.79%   71.46%   -6.33%     
==========================================
  Files          25       30       +5     
  Lines         671      729      +58     
==========================================
- Hits          522      521       -1     
- Misses        149      208      +59     

Impacted Files	Coverage Δ
src/deprecations.jl	0.00% <0.00%> (ø)
src/entropies/convenience_definitions.jl	0.00% <0.00%> (ø)
src/entropies/direct_entropies/multiscale.jl	0.00% <0.00%> (ø)
src/entropies/shannon.jl	0.00% <0.00%> (ø)
src/probabilities_estimators/kernel_density.jl	76.92% <0.00%> (ø)
...tors/permutation_ordinal/SymbolicAmplitudeAware.jl	100.00% <ø> (ø)
...permutation_ordinal/SymbolicWeightedPermutation.jl	100.00% <ø> (ø)
...imators/permutation_ordinal/spatial_permutation.jl	72.22% <ø> (ø)
...ilities_estimators/permutation_ordinal/symbolic.jl	0.00% <0.00%> (ø)
...babilities_estimators/permutation_ordinal/utils.jl	96.00% <ø> (ø)
... and 19 more

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[Datseris]

I'll review this, but we should try to add deprecations to all changed names, and move all deprecations to a top-level file deprecations.jl.

[kahaaga]

I'll review this, but we should try to add deprecations to all changed names, and move all deprecations to a top-level file deprecations.jl.

Done. I've never used deprecations before, so I'm not sure if I did this correctly.

I know @deprecate doesn't warn users unless they run Julia with --depwarn activated (which I guess the majority of users won't). I therefore kept the old code for genentropy and symbolise(x, ::SymbolicPermutation) in a deprecated folder and manually added deprecation warnings to the functions. At least I'm getting the warnings in the REPL now.

[kahaaga]

@Datseris How will the deprecations work when we push a new breaking change? When using the @deprecate macro I don't get any deprecation warnings when using genentropy (but I did so when manually adding the warnings in a separate file). If we push a new breaking version, say 2.0, will users still be able to use genentropy, or are they forced to use entropy_renyi instead?

[Datseris]

It's because of Julia's debetable decision that if you open julia without any special arguments the warnings from @deprecate are not shown. I suggest to create a dummy function genentropy(args...; kwargs...) = @warn("message"); renyi_entropy(args...; kwargs...). Notice that there is no reason to tag a 2.0 if there are deprecations and all prior code works.

[kahaaga]

Notice that there is no reason to tag a 2.0 if there are deprecations and all prior code works.

If deprecation maintains the old functionality automatically, maybe it's just fine keeping the @deprecate genentropy entropy_renyi then? New users will adapt the entropy_renyi approach (because that is all that is documented), while old users can migrate over time as they either run Julia with depwarn == true for some reason, or when reading the docs. I don't see the need to force anyone to read the deprecation warnings unless we do a major version increment.

We can state in the changelog that function names have updated.

[Datseris]

Okay, then let's settle with the @deprecate and the approach I've been using for the rest of the library, adding an update message that is displayed the first time a user uses the new version. I do it all the time in DynamicalSystems.jl.

[kahaaga]

@Datseris I'll be away until mid next week, so I most likely won't have time to do any changes to Entropies.jl until then.

Feel free to add the update message and merge the if you're happy with the current state of the PR. Otherwise, I'll pick up on it next week.

[Datseris]

Thanks a lot for your work! I'll definitely push some commits here in the meantime!

[Datseris]

I am particularly unhappy about the existence of "Shannon entropies", and I believe that it goes against our educational goal of making people understand that "for methods that first compute a probability, and then an entropy, they aren't new entropies, just new probability estimators". I am okay with having the convenience functions like wavelet_entropy but I don't think they should be documented in this way.

Instead, I propose a section in the Generalized Entropies page, called "convenience functions" that has these methods there, without much of a discussion. I'll work on this now.

[Datseris]

I don't think it makes sense for us to define a convenience function entropy_specificname for every single probability estimator we have. We should only do it for exceptionally well established names such as permutation entropy. If the name is in the title of at least one paper, hopefully more then it warrants its name. I don't think there is any paper that explicitly uses the words "the transfer operator entropy", and hence no reason to have functions like entropy_transferoperator. Similarly, no reason to have functions such as entropy_permutationweighted, as the entropy_permutation docstring should discuss alternative versions and how to obtain them the "normal" way.

I don't think packages should provide such incredible level of convenience, it is bad for maintanance and there is a point where the hit to the learning curve is just stronger than the convenience. When I write a 2 lines of code covenience function for using in my code, that only uses Julia Base functions, I don't think "oh this should have been a function already defined in Julia", and I don't expect it to. The users should think the same. It is better to know "Oh I know how to create the convenience function that gives me the amplitude weighted permutation entropy in 2 lines of code", than to think "hm, does this package export a function that computes the ...".

[Datseris]

Okay I've refactored this with my changes. There are things missing, and some files are incomplete, and I'm not sure where the new methods go. They also need to go into the changelog. Anyways, feel free to go ahead and review/critique my changes.

[Datseris]

I added one more estimator (power spectrum) via a PR.

[Datseris]

@kahaaga I'll need your help to fix the tests. They are about the in-place entropy form that I admit, I never really learned... BTW, it is not useful to test interface tests more than once. If we test entropy_renyi!(...) isa Real, we only have to do it once, not for every estimator. This is an interface test but the interface doesn't change with estimators.

[Datseris]

Wait, are the "Sample entropy
Approximate entropy
Disequilibrium" implemented somewhere in code that you just haven't pushed yet?

EDIT: Oh yes, all of these stuff are in pull requests.

[kahaaga]

EDIT: Oh yes, all of these stuff are in pull requests.

Correct. I haven't touched these since I first implemented them. I wanted to decide finally on the new API first.

Okay I've refactored this with my changes. There are things missing, and some files are incomplete, and I'm not sure where the new methods go. They also need to go into the changelog. Anyways, feel free to go ahead and review/critique my changes.
@kahaaga I'll need your help to fix the tests. They are about the in-place entropy form that I admit, I never really learned... BTW, it is not useful to test interface tests more than once. If we test entropy_renyi!(...) isa Real, we only have to do it once, not for every estimator. This is an interface test but the interface doesn't change with estimators.

I will review this PR tomorrow.