Refactor api

src/deprecated/genentropy.jl

@@ -0,0 +1,94 @@
+
+"""
+    genentropy(p::Probabilities; q = 1.0, base = MathConstants.e)
+
+Compute the generalized order-`q` entropy of some probabilities
+returned by the [`probabilities`](@ref) function. Alternatively, compute entropy
+from pre-computed `Probabilities`.
+
+    genentropy(x::Array_or_Dataset, est; q = 1.0, base)
+
+A convenience syntax, which calls first `probabilities(x, est)`
+and then calculates the entropy of the result (and thus `est` can be a
+`ProbabilitiesEstimator` or simply `ε::Real`).
+
+## Description
+
+Let ``p`` be an array of probabilities (summing to 1). Then the generalized (Rényi) entropy is
+
+```math
+H_q(p) = \\frac{1}{1-q} \\log \\left(\\sum_i p[i]^q\\right)
+```
+
+and generalizes other known entropies,
+like e.g. the information entropy
+(``q = 1``, see [^Shannon1948]), the maximum entropy (``q=0``,
+also known as Hartley entropy), or the correlation entropy
+(``q = 2``, also known as collision entropy).
+
+[^Rényi1960]: A. Rényi, *Proceedings of the fourth Berkeley Symposium on Mathematics,
+    Statistics and Probability*, pp 547 (1960)
+[^Shannon1948]: C. E. Shannon, Bell Systems Technical Journal **27**, pp 379 (1948)
+"""
+function genentropy end
+
+function genentropy(prob::Probabilities; q = 1.0, α = nothing, base = MathConstants.e)
+    Base.depwarn("`genentropy(x)` is deprecated, use `renyientropy(x)` instead.", :genentropy)
+
+    if α ≠ nothing
+        @warn "Keyword `α` is deprecated in favor of `q`."
+        q = α
+    end
+    q < 0 && throw(ArgumentError("Order of generalized entropy must be ≥ 0."))
+    haszero = any(iszero, prob)
+    p = if haszero
+        i0 = findall(iszero, prob.p)
+        # We copy because if someone initialized Probabilities with 0s, I would guess
+        # they would want to index the zeros as well. Not so costly anyways.
+        deleteat!(copy(prob.p), i0)
+    else
+        prob.p
+    end
+
+    if q ≈ 0
+        return log(base, length(p)) #Hartley entropy, max-entropy
+    elseif q ≈ 1
+        return -sum( x*log(base, x) for x in p ) #Shannon entropy
+    elseif isinf(q)
+        return -log(base, maximum(p)) #Min entropy
+    else
+        return (1/(1-q))*log(base, sum(x^q for x in p) ) #Renyi q entropy
+    end
+end
+
+function genentropy(::AbstractArray{<:Real})
+    Base.depwarn("`genentropy(x)` is deprecated, use `renyientropy(x)` instead.", :genentropy)
+    error("For single-argument input, do `genentropy(Probabilities(x))` instead.")
+end
+
+function genentropy(x::Array_or_Dataset, est; q = 1.0, α = nothing, base = MathConstants.e)
+    Base.depwarn("`genentropy(x, est)` is deprecated, use `renyientropy(x, est)` instead.", :genentropy)
+    if α ≠ nothing
+        @warn "Keyword `α` is deprecated in favor of `q`."
+        q = α
+    end
+    p = probabilities(x, est)
+    genentropy(p; q = q, base = base)
+end
+
+"""
+    genentropy!(p, x, est::ProbabilitiesEstimator; q = 1.0, base = MathConstants.e)
+Similarly with `probabilities!` this is an in-place version of `genentropy` that allows
+pre-allocation of temporarily used containers.
+Only works for certain estimators. See for example [`SymbolicPermutation`](@ref).
+"""
+function genentropy!(p, x, est; q = 1.0, α = nothing, base = MathConstants.e)
+    Base.depwarn("`genentropy(p, x, est)` is deprecated, use `renyientropy(p, x, est)` instead.", :genentropy)
+
+    if α ≠ nothing
+        @warn "Keyword `α` is deprecated in favor of `q`."
+        q = α
+    end
+    probabilities!(p, x, est)
+    genentropy(p; q = q, base = base)
+end

src/deprecated/symbolization.jl

@@ -0,0 +1,42 @@
+function symbolize(x::AbstractDataset{m, T}, est::PermutationProbabilityEstimator) where {m, T}
+    Base.depwarn("`symbolize(x, est::$P)` is deprecated, use `symbolize(x, scheme::OrdinalPattern)` instead.", :symbolize)
+
+    m >= 2 || error("Data must be at least 2-dimensional to symbolize. If data is a univariate time series, embed it using `genembed` first.")
+    s = zeros(Int, length(x))
+    symbolize!(s, x, est)
+    return s
+end
+
+function symbolize(x::AbstractVector{T}, est::P) where {T, P <: PermutationProbabilityEstimator}
+    Base.depwarn("`symbolize(x, est::$P)` is deprecated, use `symbolize(x, scheme::OrdinalPattern)` instead.", :symbolize)
+
+    τs = tuple([est.τ*i for i = 0:est.m-1]...)
+    x_emb = genembed(x, τs)
+
+    s = zeros(Int, length(x_emb))
+    symbolize!(s, x_emb, est)
+    return s
+end
+
+function symbolize!(s::AbstractVector{Int}, x::AbstractDataset{m, T}, est::SymbolicPermutation) where {m, T}
+    Base.depwarn("`symbolize!(s, x, est::SymbolicPermutation)` is deprecated, use `symbolize!(s, x, scheme::OrdinalPattern)` instead.", :symbolize)
+
+    @assert length(s) == length(x)
+    #=
+    Loop over embedding vectors `E[i]`, find the indices `p_i` that sort each `E[i]`,
+    then get the corresponding integers `k_i` that generated the
+    permutations `p_i`. Those integers are the symbols for the embedding vectors
+    `E[i]`.
+    =#
+    sp = zeros(Int, m) # pre-allocate a single symbol vector that can be overwritten.
+    fill_symbolvector!(s, x, sp, m, lt = est.lt)
+
+    return s
+end
+
+function symbolize!(s::AbstractVector{Int}, x::AbstractVector{T}, est::SymbolicPermutation) where T
+    Base.depwarn("`symbolize!(s, x, est::SymbolicPermutation)` is deprecated, use `symbolize!(s, x, scheme::OrdinalPattern)` instead.", :symbolize)
+    τs = tuple([est.τ*i for i = 0:est.m-1]...)
+    x_emb = genembed(x, τs)
+    symbolize!(s, x_emb, est)
+end

src/deprecations.jl

@@ -1 +1,5 @@
-@deprecate TimeScaleMODWT WaveletOverlap
+include("deprecated/genentropy.jl")
+include("deprecated/symbolization.jl")
+
+@deprecate TimeScaleMODWT WaveletOverlap
+@deprecate genentropy renyientropy

src/symbolization/OrdinalPattern.jl

@@ -22,6 +22,12 @@ reconstruction using embedding dimension `m` and lag `τ`. The resulting
 If using the in-place variant with univariate input, `s` must obey
 `length(s) == length(x)-(est.m-1)*est.τ`.
 
+!!! note
+    `OrdinalPattern` is intended for symbolizing *time series*. If providing a short vector,
+    say `x = [2, 5, 2, 1, 3, 4]`, then `symbolize(x, OrdinalPattern(m = 2, τ = 1)` will
+    first embed `x`, then encode/symbolize each resulting *state vector*, not the original
+    input. For symbolizing a permutation pattern, use [`encode_motif`](@ref).
+
 ## Examples
 
 ```julia