Skip to content

Commit a170f33

Browse files
kahaagaDatseris
kahaaga
and
Datseris
authored
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 <datseris.george@gmail.com> * Update src/multiscale/composite.jl Co-authored-by: George Datseris <datseris.george@gmail.com> * Update docs/src/multiscale.md Co-authored-by: George Datseris <datseris.george@gmail.com> * Update docs/src/multiscale.md Co-authored-by: George Datseris <datseris.george@gmail.com> * Update docs/src/multiscale.md Co-authored-by: George Datseris <datseris.george@gmail.com> * Update src/multiscale/multiscale.jl Co-authored-by: George Datseris <datseris.george@gmail.com> * Update src/multiscale/multiscale.jl Co-authored-by: George Datseris <datseris.george@gmail.com> * Update src/multiscale/multiscale.jl Co-authored-by: George Datseris <datseris.george@gmail.com> * 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 <datseris.george@gmail.com> --------- Co-authored-by: George Datseris <datseris.george@gmail.com>
1 parent 5478174 commit a170f33

20 files changed

+819
-337
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Changelog is kept with respect to version 0.11 of Entropies.jl. From version v2.
44

55
## 3.5
66

7+
- New multiscale API.
78
- New spatial outcome space: `SpatialBubbleSortSwaps`.
89
- 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.
910

‎docs/make.jl

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ pages = [
1414
"probabilities.md",
1515
"information_measures.md",
1616
"complexity.md",
17+
"multiscale.md",
1718
"convenience.md",
1819
"examples.md",
1920
"devdocs.md",

‎docs/src/convenience.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# [Convenience functions](@id convenience)
22

3+
## Common entropy-based measures
4+
35
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.
46

57
We emphasize that these functions really aren't anything more than

‎docs/src/dev/multiscale.md

Lines changed: 0 additions & 22 deletions
This file was deleted.

‎docs/src/devdocs.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,3 +101,23 @@ This amounts to adding a new definition of an information measure, not an estima
101101
probability distribution with a known number of elements, implementing dispatch for
102102
[`information_maximum`](@ref) automatically enables [`information_normalized`](@ref)
103103
for your type.
104+
105+
## Adding a new `MultiScaleAlgorithm`
106+
107+
A new `MultiScaleAlgorithm` is simply a new way of coarse-graining input time series
108+
across multiple scales.
109+
110+
### Mandatory steps
111+
112+
1. Define a new type `YourNewMultiScaleType <: MultiScaleAlgorithm`. This type will
113+
define how coarse graining is performed.
114+
2. Implement dispatch for [`downsample`](@ref), which transforms the original time series
115+
into a vector of coarse-grained time series, one per scale (may be nested if needed).
116+
3. Implement dispatch for the internal `apply_multiscale` function.
117+
4. Add an entry for your new type in the `multiscale.md` file.
118+
5. Add tests for your new type. You specifically need to implement analytical tests
119+
that verify that [`downsample`](@ref) is correctly implemented. For API tests,
120+
simply copy the tests from e.g. `tests/multiscale/Composite.jl`, and replace the
121+
multiscale coarse-graining algorithm with an instance of your algorithm.
122+
6. Hooray! You're new coarse-graining procedure is integrated with the entire
123+
ComplexityMeasures.jl ecosystem!

‎docs/src/examples.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -990,3 +990,28 @@ lines!(ax, max_curve; color=:black)
990990
axislegend(; position=:lt)
991991
fig
992992
```
993+
994+
## [Complexity: multiscale](@id multiscale_example)
995+
996+
Let's use [`multiscale`](@ref) analysis to investigate the [`SampleEntropy`](@ref) of a
997+
signal across coarse-graining scales.
998+
999+
```@example
1000+
using ComplexityMeasures
1001+
using CairoMakie
1002+
1003+
N, a = 2000, 20
1004+
t = LinRange(0, 2*a*π, N)
1005+
scales = 1:10
1006+
1007+
x = repeat([-5:5 |> collect; 4:-1:-4 |> collect], N ÷ 20);
1008+
y = sin.(t .+ cos.(t/0.5)) .+ 0.2 .* x
1009+
hs = multiscale_normalized(RegularDownsampling(; scales), SampleEntropy(y), y)
1010+
1011+
fig = Figure()
1012+
ax1 = Axis(fig[1,1]; ylabel = "y")
1013+
lines!(ax1, t, y; color = Cycled(1));
1014+
ax2 = Axis(fig[2, 1]; ylabel = "Sample entropy (h)", xlabel = "Scale")
1015+
scatterlines!(ax2, scales |> collect, hs; color = Cycled(1));
1016+
fig
1017+
```

‎docs/src/multiscale.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Multiscale
2+
3+
## Introduction
4+
5+
Multiscale complexity analysis is pervasive in the nonlinear time series analysis
6+
literature. Although their names, like "refined composite multiscale dispersion entropy",
7+
might seem daunting, they're actually conceptually very simple. A multiscale complexity
8+
measure is just any regular complexity measure
9+
computed on several gradually more coarse-grained samplings of the input data
10+
([example](@ref multiscale_example)).
11+
12+
We've generalized this type of analysis to work with complexity measure that can
13+
be estimated with ComplexityMeasures.jl.
14+
15+
## Multiscale API
16+
17+
The multiscale API is defined by the functions
18+
19+
- [`multiscale`](@ref)
20+
- [`multiscale_normalized`](@ref)
21+
- [`downsample`](@ref)
22+
23+
which dispatch any of the [`MultiScaleAlgorithm`](@ref)s listed below.
24+
25+
```@docs
26+
multiscale
27+
multiscale_normalized
28+
MultiScaleAlgorithm
29+
RegularDownsampling
30+
CompositeDownsampling
31+
downsample
32+
```
33+
34+
## Example literature methods
35+
36+
A non-exhaustive list of literature methods, and the syntax to compute them, are listed
37+
below. Please open an issue or make a pull-request to
38+
[ComplexityMeasures.jl](https://github.com/JuliaDynamics/ComplexityMeasures.jl) if you
39+
find a literature method missing from this list, or if you publish a paper based on some
40+
new multiscale combination.
41+
42+
| Method | Syntax example | Reference |
43+
| ----------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------ |
44+
| Refined composite multiscale dispersion entropy | `multiscale(CompositeDownsampling(), Dispersion(), est, x, normalized = true)` | [Azami2017](@cite) |
45+
| Multiscale sample entropy (first moment) | `multiscale(RegularDownsampling(f = mean), SampleEntropy(x), x)` | [Costa2002](@cite) |
46+
| Generalized multiscale sample entropy (second moment) | `multiscale(RegularDownsampling(f = std), SampleEntropy(x), x)` | [Costa2015](@cite) |

‎docs/src/multiscale.txt

Lines changed: 0 additions & 36 deletions
This file was deleted.

0 commit comments

Comments
 (0)