add docstrings to convenience calls

Author: Datseris

src/entropies/convenience_definitions.jl

@@ -1,13 +1,41 @@
 # This file defines and exports some convenience definition of entropies
 # for commonly used names in the literature. They aren't actually new entropies
 # as discussed extensively in the documentation.
+export entropy_permutation, entropy_spatial_permutation, entropy_wavelet
 
-function entropy_permutation(args...)
+"""
+    entropy_permutation(x; τ = 1, m = 3, base = MathConstants.e)
 
+Compute the permutation entropy of order `m` with delay/lag `τ`.
+This function is just a convenience call to:
+```julia
+est = SymbolicPermutation(; m, τ)
+entropy_renyi(x, est; base, q = 1)
+```
+See [`SymbolicPermutation`](@ref) for more info.
+Similarly, one can use `SymbolicWeightedPermutation` or `SymbolicAmplitudeAwarePermutation`
+for the weighted/amplitude-aware versions.
+"""
+function entropy_permutation(x; τ = 1, m = 3, base = MathConstants.e)
+    est = SymbolicPermutation(; m, τ)
+    entropy_renyi(x, est; base, q = 1)
 end
 
-function entropy_spatial_permutation(args...)
+"""
+    entropy_spatial_permutation(x, stencil, periodic = true; kwargs...)
 
+Compute the spatial permutation entropy of `x` given the `stencil`.
+Here `x` must be a matrix or higher dimensional `Array` containing spatial data.
+This function is just a convenience call to:
+```julia
+est = SpatialSymbolicPermutation(stencil, x, periodic)
+entropy_renyi(x, est; kwargs..., q = 1)
+```
+See [`SpatialSymbolicPermutation`](@ref) for more info, or how to encode stencils.
+"""
+function entropy_spatial_permutation(x, stencil, periodic = true; kwargs...)
+    est = SpatialSymbolicPermutation(stencil, x, periodic)
+    entropy_renyi(x, est; kwargs..., q = 1)
 end
 
 """
@@ -18,7 +46,7 @@ Compute the wavelet entropy. This function is just a convenience call to:
 est = WaveletOverlap(wavelet)
 entropy_renyi(x, est; base, q = 1)
 ```
-See [`WaveletOverlap`](@ref) for more.
+See [`WaveletOverlap`](@ref) for more info.
 """
 function entropy_wavelet(x; wavelet = Wavelets.WT.Daubechies{12}(), base = MathConstants.e)
     est = WaveletOverlap(wavelet)

src/probabilities_estimators/permutation_ordinal/SymbolicPermutation.jl

@@ -13,6 +13,7 @@ abstract type PermutationProbabilityEstimator <: ProbabilitiesEstimator end
 Symbolic, permutation-based probabilities/entropy estimators.
 `m` is the permutation order (or the symbol size or the embedding dimension) and
 `τ` is the delay time (or lag).
+They are used to define the permutation entropies[^BandtPompe2002].
 
 ## Repeated values during symbolization
 

src/probabilities_estimators/permutation_ordinal/spatial_permutation.jl

@@ -24,7 +24,7 @@ The length of the stencil decides the order of the permutation entropy, and the
 within the stencil dictates the order that pixels are compared with.
 The pixel without any offset is always first in the order.
 
-After having defined `est`, one calculates the permutation entropy of ordinal patterns
+After having defined `est`, one calculates the spatial permutation entropy
 by calling [`entropy_renyi`](@ref) with `est`, and with the array data.
 To apply this to timeseries of spatial data, simply loop over the call, e.g.:
 ```julia