FixedRectangularBinning symbolization and Diversity probabilities

[kahaaga]

What's new in this PR?

This PR implements the diversity entropy (Wang et al., 2020), and its underlying probability estimator.

Changes/additions:

• FixedRectangularBinning symbolization scheme, which is required for the new method (fixes Rectangular binning with custom (fixed) ranges #118).
• alphabet_length implemented for both RectangularBinning and FixedRectangularBinning (fixes Implement alphabet_length for histograms #103).
• Added Diversity probability estimator, with analytical tests from the paper.
• Documentation entries for the new FixedRectangularBinning and Diversity.
• Modified docstring for RectangularBinning to highlight how it is different from FixedRectangularBinning.

References

Wang, X., Si, S., & Li, Y. (2020). Multiscale diversity entropy: A novel dynamical measure for fault diagnosis of rotating machinery. IEEE Transactions on Industrial Informatics, 17(8), 5419-5429.

[codecov]

Codecov Report

Merging #127 (8a625b4) into main (e85b0fb) will increase coverage by 1.43%.
The diff coverage is 84.78%.

@@            Coverage Diff             @@
##             main     #127      +/-   ##
==========================================
+ Coverage   80.17%   81.61%   +1.43%     
==========================================
  Files          35       36       +1     
  Lines         792      854      +62     
==========================================
+ Hits          635      697      +62     
  Misses        157      157              

Impacted Files	Coverage Δ
src/complexity_measures/sample_entropy.jl	80.55% <ø> (ø)
src/encoding/outcomes.jl	0.00% <0.00%> (ø)
...imators/permutation_ordinal/SymbolicPermutation.jl	72.97% <ø> (ø)
...imators/permutation_ordinal/spatial_permutation.jl	91.30% <ø> (ø)
...ities_estimators/histograms/rectangular_binning.jl	81.33% <78.94%> (-11.53%)	⬇️
.../complexity_measures/reverse_dispersion_entropy.jl	100.00% <100.00%> (ø)
src/encoding/gaussian_cdf.jl	100.00% <100.00%> (ø)
src/encoding/ordinal_pattern.jl	100.00% <100.00%> (ø)
.../probabilities_estimators/dispersion/dispersion.jl	76.19% <100.00%> (ø)
...rc/probabilities_estimators/diversity/diversity.jl	100.00% <100.00%> (ø)
... and 7 more

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

[Datseris]

(tag me explicitly when you think this is final and ready to review)

[kahaaga]

(tag me explicitly when you think this is final and ready to review)

@Datseris If the tests pass and the documentation looks good after the latest commit, this is ready for reviewing.

[Datseris]

What is RectangularBinMapping? Where does it come from? Does it replace the RectangularBinEncoder I have created? If so, why is the git diff like this? It never shows the RectangularBinEncoder being replcaed by the Mapping.

p.s.: The fact that this new FixedRectangularBinning was written in the same file as the normal binning and was written in the lines before the normal binning made the git diff unecessarily difficult to review. If you check, it seems like most of the RectangularBinning code is overwritten/changed in this PR.

[Datseris]

I'm confused here. We get a bin_estimator that contains the binning we give to ValueHistogram, but then in the end we actually only use the binning...? What's the purpose of bin_estiamtor then...

[Datseris]

Furthermore I thought we completely dissallowed use probabilities with anything else besides <: ProbaiblitiesEstimator. So how does this call using a binning works?

[kahaaga]

Furthermore I thought we completely dissallowed use probabilities with anything else besides <: ProbaiblitiesEstimator.

I can't remember anymore where the discussion ended up. There were probably some good arguments for/against in a PR/issue somewhere.

So how does this call using a binning works?

It just does

function probabilities(x::Vector_or_Dataset, binning::Floating_or_Fixed_RectBinning)
    fasthist!(x, binning)[1]
end

which is convenient, because fasthist isn't exported and writing probabilities(x, ValueHistogram(RectangularBinning()) is verbose.

If we don't want to have these convenience methods, it's straight-forward to just remove them and let

function probabilities(x::AbstractVector{T}, est::Diversity) where T <: Real
    ds, binning = similarities_and_binning(x, est)
    return fasthist!(ds, binning)[1]
end

and the same for probabilities_and_outcomes.

[Datseris]

ValueHistogram(RectangularBinning()) is verbose. Yes, but we have allowed ValueHistogram(ε) to initialize the binning internally. I think we should stick with not allowing probabilities to take anything other than an estimator.

[kahaaga]

What is RectangularBinMapping? Where does it come from? Does it replace the RectangularBinEncoder I have created? If so, why is the git diff like this? It never shows the RectangularBinEncoder being replcaed by the Mapping.

The RectangularBinMapping is exactly RectangularBinEncoder, just renamed, so that all encoding schemes have a common naming convention (like GaussianMapping and OrdinalMapping). Nothing else should have changed.

p.s.: The fact that this new FixedRectangularBinning was written in the same file as the normal binning and was written in the lines before the normal binning made the git diff unecessarily difficult to review. If you check, it seems like most of the RectangularBinning code is overwritten/changed in this PR.

The git diff became weird when I merged main into the diversity_probs branch. I guess it was because of what you said about the new lines added before the existing ones?

[Datseris]

We should make Entropies reexport DelayEmbeddings I guess

[Datseris]

The RectangularBinMapping is exactly RectangularBinEncoder, just renamed, so that all encoding schemes have a common naming convention (like GaussianMapping and OrdinalMapping).

But these aren't intuitive names though. OrdinalPatterns is more intuitive than OrdinalMapping. I would argue that once again we violate the "one word per concept principle". Why are we using Mapping here? Aren't these Encodings? We decided on the Encoding word, we might as well use it. Hence, RectangularBinEncoding, OrdinalPatternEncoding, etc.

[kahaaga]

Ok, I think I addressed all your comments now, @Datseris. The CI docs still fail to run, though, and it seems to be related to the use of ChaosTools in the docs (but they look good locally).

[Datseris]

ill take care of the docs in a different PR