Encoding for binnings (#177)

* only convert to probabilities at the very last step

* put the `vec` in there

* finish `encode/decode` and linear indexing

* rework valuehistogram to store the encoding directly

* remove special clauses for input timeseries

* make histogram size part of the bin encoding

* massive simplification of all binning source

* WIP fixing tests

Also ported explicitly to StateSpaceSets

* use next float also in the estimation of histogram size

* use encding -1 for points outside histogram

* declare encoding api

* fix all tests!

* Use StateSpaceSets for tests, and explicit imports

* delete weird unknown "DS_Store" files

* bring back lost value histogram test file

* update api to correct order for probs

* all tests are passing

Co-authored-by: Kristian Haaga <[email protected]>

Author: Datseris

.DS_Store

@@ -16,19 +16,21 @@ Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Scratch = "6c6a2e73-6563-6170-7368-637461726353"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
+StateSpaceSets = "40b095a5-5852-4c12-98c7-d43bf788e795"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 Wavelets = "29a6e085-ba6d-5f35-a997-948ac2efa89a"
 
 [compat]
 Combinatorics = "1"
-DelayEmbeddings = "2.5"
+DelayEmbeddings = "2.6"
 Distances = "0.9, 0.10"
 FFTW = "1"
 Neighborhood = "0.2.4"
 QuadGK = "2"
 Scratch = "1"
 SpecialFunctions = "0.10, 1.0, 2"
+StateSpaceSets = "0.1.2, 1"
 StaticArrays = "0.12, 1.0"
 Wavelets = "0.9"
 julia = "1.5"

Project.toml

@@ -7,10 +7,11 @@ Good practices in developing a code base apply in every Pull Request. The [Good
 ### Mandatory steps
 1. Decide on the outcome space and how the estimator will map probabilities to outcomes.
 2. Define your type and make it subtype `ProbabilitiesEstimator`.
-3. Add a docstring to your type following the style of the docstrings of other estimators.
-4. Implement dispatch for [`probabilities_and_outcomes`](@ref).
-5. Implement dispatch for [`outcome_space`](@ref).
-6. Add your type to the list in the docstring of [`ProbabilitiyEstimator`](@ref).
+4. Add a docstring to your type following the style of the docstrings of other estimators.
+5. If suitable, the estimator may be able to operate based on [`Encoding`]s. If so, it is preferred to implement an `Encoding` subtype and extend the methods [`encode`](@ref) and [`decode`](@ref). This will allow your probabilities estimator to be used with a larger span of entropy and complexity methods without additional effort.
+6. Implement dispatch for [`probabilities_and_outcomes`](@ref) and your probabilities estimator type.
+7. Implement dispatch for [`outcome_space`](@ref) and your probabilities estimator type.
+8. Add your probabilities estimator type to the list in the docstring of [`ProbabilitiyEstimator`](@ref), and if you also made an encoding, add it to the [`Encoding`](@ref) docstring.
 
 ### Optional steps
 You may extend any of the following functions if there are potential performance benefits in doing so:

docs/.DS_Store

@@ -9,19 +9,21 @@ To install it, run `import Pkg; Pkg.add("Entropies")`.
 """
 module Entropies
 
-using DelayEmbeddings
-using DelayEmbeddings: AbstractDataset, Dataset, dimension
-export AbstractDataset, Dataset
-export DelayEmbeddings
+using StateSpaceSets
+export Dataset, SVector
+using DelayEmbeddings: embed, genembed
+
 const Array_or_Dataset = Union{<:AbstractArray{<:Real}, <:AbstractDataset}
 const Vector_or_Dataset = Union{<:AbstractVector{<:Real}, <:AbstractDataset}
 
+# Core API types and functions
 include("probabilities.jl")
 include("entropy.jl")
-include("encoding/outcomes.jl")
+include("encodings.jl")
+# Library implementations (files include other files)
 include("probabilities_estimators/probabilities_estimators.jl")
 include("entropies/entropies.jl")
-
+include("encoding/all_encodings.jl")
 include("deprecations.jl")
 
 

docs/src/devdocs.md

@@ -0,0 +1,3 @@
+include("utils.jl")
+include("gaussian_cdf.jl")
+include("ordinal_pattern.jl")

src/Entropies.jl

@@ -0,0 +1,31 @@
+export Encoding, encode, decode
+
+"""
+    Encoding
+
+The supertype for all encoding schemes. Encodings **always encode elements of
+input data into the positive integers**. The encoding API is defined by the
+functions [`encode`](@ref) and [`decode`](@ref).
+Some probability estimators utilize encodings internally.
+
+Current available encodings are:
+
+- [`OrdinalPatternEncoding`](@ref).
+- [`GaussianCDFEncoding`](@ref).
+- [`RectangularBinEncoding`](@ref).
+"""
+abstract type Encoding end
+
+"""
+    encode(χ, e::Encoding) -> i::Int
+Encoding an element `χ ∈ x` of input data `x` (those given to [`probabilities`](@ref))
+using encoding `e`.
+"""
+function encode end
+
+"""
+    decode(i::Int, e::Encoding) -> ω
+Decode an encoded element `i::Int` into the outcome it corresponds to `ω ∈ Ω`.
+`Ω` is the [`outcome_space`](@ref) of a probabilities estimator that uses encoding `e`.
+"""
+function decode end

src/encoding/all_encodings.jl

@@ -42,6 +42,7 @@ Base.IteratorSize(::Probabilities) = Base.HasLength()
 @inline Base.sum(::Probabilities{T}) where T = one(T)
 
 """
+ProbabilitiesEstimator
 The supertype for all probabilities estimators.
 
 In Entropies.jl, probability distributions are estimated from data by defining a set of
@@ -203,5 +204,5 @@ Equivalent with `probabilities_and_outcomes(x, est)[2]`, but for some estimators
 it may be explicitly extended for better performance.
 """
 function outcomes(x, est::ProbabilitiesEstimator)
-    return probabilities_and_outcomes(x, est)[2]
+    return probabilities_and_outcomes(est, x)[2]
 end