Finish multiscale API (#404)

* Finish multiscale API * Fix erroneous docstring for `StatisticalComplexity` Fixes #401 * Improve docs * Update docs/src/multiscale.md Co-authored-by: George Datseris <[email protected]> * Update src/multiscale/composite.jl Co-authored-by: George Datseris <[email protected]> * Update docs/src/multiscale.md Co-authored-by: George Datseris <[email protected]> * Update docs/src/multiscale.md Co-authored-by: George Datseris <[email protected]> * Update docs/src/multiscale.md Co-authored-by: George Datseris <[email protected]> * Update src/multiscale/multiscale.jl Co-authored-by: George Datseris <[email protected]> * Update src/multiscale/multiscale.jl Co-authored-by: George Datseris <[email protected]> * Update src/multiscale/multiscale.jl Co-authored-by: George Datseris <[email protected]> * Adjust interface so that scale are in constructors + more tests * Fix doc example * New syntax in doc example * Update docs/src/multiscale.md Co-authored-by: George Datseris <[email protected]> --------- Co-authored-by: George Datseris <[email protected]>
JuliaDynamics · Jun 4, 2024 · a170f33 · a170f33 · kahaaga · Jun 4, 2024
1 parent 5478174
commit a170f33
Show file tree

Hide file tree

Showing 20 changed files with 819 additions and 337 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@ Changelog is kept with respect to version 0.11 of Entropies.jl. From version v2.
 
 ## 3.5
 
+- New multiscale API.
 - New spatial outcome space: `SpatialBubbleSortSwaps`.
 - A script in the documentation now calculates explicitly the total possible complexity measures one can estimate with ComplexityMeasures.jl. For version 3.5 this is roughly 1,600.
 

diff --git a/docs/make.jl b/docs/make.jl
@@ -14,6 +14,7 @@ pages = [
     "probabilities.md",
     "information_measures.md",
     "complexity.md",
+    "multiscale.md",
     "convenience.md",
     "examples.md",
     "devdocs.md",

diff --git a/docs/src/convenience.md b/docs/src/convenience.md
@@ -1,5 +1,7 @@
 # [Convenience functions](@id convenience)
 
+## Common entropy-based measures
+
 We provide a few convenience functions for widely used names for entropy or "entropy-like" quantities. Other arbitrary specialized convenience functions can easily be defined in a couple lines of code.
 
 We emphasize that these functions really aren't anything more than

diff --git a/docs/src/dev/multiscale.md b/docs/src/dev/multiscale.md
diff --git a/docs/src/devdocs.md b/docs/src/devdocs.md
@@ -101,3 +101,23 @@ This amounts to adding a new definition of an information measure, not an estima
     probability distribution with a known number of elements, implementing dispatch for
     [`information_maximum`](@ref) automatically enables [`information_normalized`](@ref)
     for your type.
+
+## Adding a new `MultiScaleAlgorithm`
+
+A new `MultiScaleAlgorithm` is simply a new way of coarse-graining input time series 
+across multiple scales.
+
+### Mandatory steps
+
+1. Define a new type `YourNewMultiScaleType <: MultiScaleAlgorithm`. This type will
+    define how coarse graining is performed.
+2. Implement dispatch for [`downsample`](@ref), which transforms the original time series
+    into a vector of coarse-grained time series, one per scale (may be nested if needed).
+3. Implement dispatch for the internal `apply_multiscale` function.
+4. Add an entry for your new type in the `multiscale.md` file.
+5. Add tests for your new type. You specifically need to implement analytical tests
+    that verify that [`downsample`](@ref) is correctly implemented. For API tests,
+    simply copy the tests from e.g. `tests/multiscale/Composite.jl`, and replace the
+    multiscale coarse-graining algorithm with an instance of your algorithm.
+6. Hooray! You're new coarse-graining procedure is integrated with the entire
+    ComplexityMeasures.jl ecosystem!
diff --git a/docs/src/examples.md b/docs/src/examples.md
@@ -990,3 +990,28 @@ lines!(ax, max_curve; color=:black)
 axislegend(; position=:lt)
 fig
 ```
+
+## [Complexity: multiscale](@id multiscale_example)
+
+Let's use [`multiscale`](@ref) analysis to investigate the [`SampleEntropy`](@ref) of a
+signal across coarse-graining scales.
+
+```@example
+using ComplexityMeasures
+using CairoMakie
+
+N, a = 2000, 20
+t = LinRange(0, 2*a*π, N)
+scales = 1:10
+
+x = repeat([-5:5 |> collect; 4:-1:-4 |> collect], N ÷ 20);
+y = sin.(t .+ cos.(t/0.5)) .+ 0.2 .* x
+hs = multiscale_normalized(RegularDownsampling(; scales), SampleEntropy(y), y)
+
+fig = Figure()
+ax1 = Axis(fig[1,1]; ylabel = "y")
+lines!(ax1, t, y; color = Cycled(1));
+ax2 = Axis(fig[2, 1]; ylabel = "Sample entropy (h)", xlabel = "Scale")
+scatterlines!(ax2, scales |> collect, hs; color = Cycled(1));
+fig
+```
diff --git a/docs/src/multiscale.md b/docs/src/multiscale.md
@@ -0,0 +1,46 @@
+# Multiscale
+
+## Introduction
+
+Multiscale complexity analysis is pervasive in the nonlinear time series analysis
+literature. Although their names, like "refined composite multiscale dispersion entropy",  
+might seem daunting, they're actually conceptually very simple. A multiscale complexity
+measure is just any regular complexity measure
+computed on several gradually more coarse-grained samplings of the input data
+([example](@ref multiscale_example)).
+
+We've generalized this type of analysis to work with complexity measure that can 
+be estimated with ComplexityMeasures.jl.
+
+## Multiscale API
+
+The multiscale API is defined by the functions
+
+- [`multiscale`](@ref)
+- [`multiscale_normalized`](@ref)
+- [`downsample`](@ref)
+
+which dispatch any of the [`MultiScaleAlgorithm`](@ref)s listed below.
+
+```@docs
+multiscale
+multiscale_normalized
+MultiScaleAlgorithm
+RegularDownsampling
+CompositeDownsampling
+downsample
+```
+
+## Example literature methods
+
+A non-exhaustive list of literature methods, and the syntax to compute them, are listed
+below. Please open an issue or make a pull-request to
+[ComplexityMeasures.jl](https://github.com/JuliaDynamics/ComplexityMeasures.jl) if you
+find a literature method missing from this list, or if you publish a paper based on some
+new multiscale combination.
+
+| Method                                                | Syntax example                                                                 | Reference          |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------ |
+| Refined composite multiscale dispersion entropy       | `multiscale(CompositeDownsampling(), Dispersion(), est, x, normalized = true)` | [Azami2017](@cite) |
+| Multiscale sample entropy (first moment)              | `multiscale(RegularDownsampling(f = mean), SampleEntropy(x), x)`               | [Costa2002](@cite) |
+| Generalized multiscale sample entropy (second moment) | `multiscale(RegularDownsampling(f = std), SampleEntropy(x),  x)`               | [Costa2015](@cite) |
diff --git a/docs/src/multiscale.txt b/docs/src/multiscale.txt