Rename all "traditional" references to "separated" (#125)

* rename traditional to separated folder * rename `optimal_traditional_de` to separated * separate bundle function to dedicated block * use separated in docstring * bump version * correct usage of `end` in embedding tests * delete old file * rename to separated in tests as well * improve/clarify embedding tests * update docs to Juliadynamics style * correct length in embedding * update github actions * fix tests! * actually fix tests * remove failing test
JuliaDynamics · Aug 4, 2023 · ab2a1ef · ab2a1ef
1 parent 56c2537
commit ab2a1ef
Show file tree

Hide file tree

Showing 18 changed files with 97 additions and 335 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -24,17 +24,17 @@ jobs:
       # Cancel ongoing CI test runs if pushing to branch again before the previous tests
       # have finished
       - name: Cancel ongoing test runs for previous commits
-        uses: styfle/cancel-workflow-action@0.11.0
+        uses: styfle/cancel-workflow-action@0.6.0
         with:
           access_token: ${{ github.token }}
 
       # Do tests
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@v1
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: actions/cache@v3
+      - uses: actions/cache@v1
         env:
           cache-name: cache-artifacts
         with:
@@ -45,8 +45,9 @@ jobs:
             ${{ runner.os }}-test-
             ${{ runner.os }}-
       - uses: julia-actions/julia-buildpkg@v1
+
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v1
         with:
           file: lcov.info
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -67,17 +67,17 @@ Now DelayEmbeddings.jl really is only about delay coordinate embedding methods.
 * `reconstruct` is deprecated in favor of `embed`.
 
 # v1.12.0
-* Possible delay times in `optimal_traditional_de` are now `1:100` for increased accuracy.
+* Possible delay times in `optimal_separated_de` are now `1:100` for increased accuracy.
 * New method for univariate non-unified delay embedding by Hegger, Kantz
 * It is now possible to `embed` in one dimension (which just returns the vector as a StateSpaceSet)
-* New function `optimal_traditional_de` for automated delay embeddings
+* New function `optimal_separated_de` for automated delay embeddings
 * `delay_afnn, delay_ifnn, delay_fnn, delay_f1nn` are part of public API now.
 * The argument `γs` and the function `reconstruct` is starting to be phased out in
   favor of `ds` and `embed`.
 * Multi-timeseries via `reconstruct` or `embed` is deprecated in favor of using `genembed`.
 
 ## Deprecations
-* Using `estimate_dimension` is deprecated in favor of either calling `afnn, fnn, ...` directly or using the function `optimal_traditional_de`
+* Using `estimate_dimension` is deprecated in favor of either calling `afnn, fnn, ...` directly or using the function `optimal_separated_de`
 
 # v1.11.0
 * Dropped RecipesBase

diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "DelayEmbeddings"
 uuid = "5732040d-69e3-5649-938a-b6b4f237613f"
 repo = "https://github.com/JuliaDynamics/DelayEmbeddings.jl.git"
-version = "2.7.1"
+version = "2.7.2"
 
 [deps]
 Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"

diff --git a/docs/make.jl b/docs/make.jl
@@ -1,41 +1,22 @@
 cd(@__DIR__)
 
+using DelayEmbeddings
+
 import Downloads
 Downloads.download(
-    "https://raw.githubusercontent.com/JuliaDynamics/doctheme/master/apply_style.jl",
-    joinpath(@__DIR__, "apply_style.jl")
+    "https://raw.githubusercontent.com/JuliaDynamics/doctheme/master/build_docs_with_style.jl",
+    joinpath(@__DIR__, "build_docs_with_style.jl")
 )
-include("apply_style.jl")
+include("build_docs_with_style.jl")
 
-using DelayEmbeddings
-
-DelayEmbeddings_PAGES = [
+pages = [
     "index.md",
     "embed.md",
     "separated.md",
     "unified.md",
 ]
 
-makedocs(
-    modules = [DelayEmbeddings, StateSpaceSets],
-    format = Documenter.HTML(
-        prettyurls = CI,
-        assets = [
-            asset("https://fonts.googleapis.com/css?family=Montserrat|Source+Code+Pro&display=swap", class=:css),
-        ],
-        collapselevel = 3,
-    ),
-    sitename = "DelayEmbeddings.jl",
-    authors = "George Datseris",
-    pages = DelayEmbeddings_PAGES,
-    doctest = false,
-    draft = false,
+build_docs_with_style(pages, DelayEmbeddings, StateSpaceSets;
+    authors = "George Datseris <[email protected]>, Hauke Kraemer",
+    expandfirst = ["index.md"], #  this is the first script that loads colorscheme
 )
-
-if CI
-    deploydocs(
-        repo = "github.com/JuliaDynamics/DelayEmbeddings.jl.git",
-        target = "build",
-        push_preview = true
-    )
-end
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -16,6 +16,6 @@ There are two approaches for estimating optimal parameters to do delay embedding
 1. **Separated**, where one tries to find the best value for a delay time `τ` and then an optimal embedding dimension `d`.
 2. **Unified**, where at the same time an optimal combination of `τ, d` is found.
 
-The separated approach is something "old school", while recent scientific research has shifted almost exclusively to unified approaches. This page describes algorithms belonging to the separated approach, which is mainly done by the function [`optimal_traditional_de`](@ref).
+The separated approach is something "old school", while recent scientific research has shifted almost exclusively to unified approaches. This page describes algorithms belonging to the separated approach, which is mainly done by the function [`optimal_separated_de`](@ref).
 
 The unified approach is discussed in the [Unified optimal embedding](@ref) page.
diff --git a/docs/src/separated.md b/docs/src/separated.md
@@ -1,11 +1,19 @@
 # Separated optimal embedding
 This page discusses and provides algorithms for estimating optimal parameters to do Delay Coordinates Embedding (DCE) with using the separated approach.
 
+## Automated function
+
+```@docs
+optimal_separated_de
+```
+
 ## Optimal delay time
+
 ```@docs
 estimate_delay
 exponential_decay_fit
 ```
+
 ### Self Mutual Information
 
 ```@docs
@@ -16,8 +24,8 @@ Notice that mutual information between two *different* timeseries x, y exists in
 It is also trivial to define it yourself using `entropy` from `ComplexityMeasures`.
 
 ## Optimal embedding dimension
+
 ```@docs
-optimal_traditional_de
 delay_afnn
 delay_ifnn
 delay_fnn
@@ -26,6 +34,7 @@ DelayEmbeddings.stochastic_indicator
 ```
 
 ## Example
+
 ```@example MAIN
 using DelayEmbeddings, CairoMakie
 using DynamicalSystemsBase
@@ -50,7 +59,7 @@ ax = Axis(fig[1,1]; xlabel = "embedding dimension", ylabel = "estimator")
 for (i, method) in enumerate(["afnn", "fnn", "f1nn", "ifnn"])
     # Plot statistic used to estimate optimal embedding
     # as well as the automated output embedding
-    𝒟, τ, E = optimal_traditional_de(x, method; dmax)
+    𝒟, τ, E = optimal_separated_de(x, method; dmax)
     lines!(ax, 1:dmax, E; label = method, marker = :circle, color = Cycled(i))
     optimal_d = size(𝒟, 2)
     ## Scatter the optimal embedding dimension as a lager marker

diff --git a/src/DelayEmbeddings.jl b/src/DelayEmbeddings.jl
@@ -13,9 +13,9 @@ using Reexport
 include("embeddings/embed.jl")
 include("embeddings/genembed.jl")
 include("utils.jl")
-include("traditional_de/estimate_delay.jl")
-include("traditional_de/estimate_dimension.jl")
-include("traditional_de/automated.jl")
+include("separated_de/estimate_delay.jl")
+include("separated_de/estimate_dimension.jl")
+include("separated_de/automated.jl")
 
 include("unified_de/pecora.jl")
 include("unified_de/uzal_cost.jl")

diff --git a/src/deprecate.jl b/src/deprecate.jl
@@ -0,0 +1 @@
+@deprecate optimal_traditional_de optimal_separated_de
diff --git a/src/embeddings/genembed.jl b/src/embeddings/genembed.jl
@@ -5,6 +5,7 @@ export GeneralizedEmbedding, genembed
 
 """
     GeneralizedEmbedding(τs, js = ones(length(τs)), ws = nothing) -> `embedding`
+
 Return a delay coordinates embedding structure to be used as a function.
 Given a timeseries *or* trajectory (i.e. `StateSpaceSet`) `s` and calling
 ```julia
@@ -82,7 +83,8 @@ max(1, (-minimum(ge.τs) + 1)):min(length(s), length(s) - maximum(ge.τs))
 
 
 """
-    genembed(s, τs, js = ones(...); ws = nothing) → dataset
+    genembed(s, τs, js = ones(...); ws = nothing) → ssset
+
 Create a generalized embedding of `s` which can be a timeseries or arbitrary `StateSpaceSet`,
 and return the result as a new `StateSpaceSet`.
 

diff --git a/src/traditional_de/automated.jl → src/separated_de/automated.jl b/src/traditional_de/automated.jl → src/separated_de/automated.jl
@@ -1,10 +1,10 @@
-export optimal_traditional_de
+export optimal_separated_de
 
 """
-    optimal_traditional_de(s, method = "afnn", dmethod = "mi_min"; kwargs...) → 𝒟, τ, E
+    optimal_separated_de(s, method = "afnn", dmethod = "mi_min"; kwargs...) → 𝒟, τ, E
 
 Produce an optimal delay embedding `𝒟` of the given timeseries `s` by
-using the traditional approach of first finding an optimal (and constant) delay
+using the *separated* approach of first finding an optimal (and constant) delay
 time using [`estimate_delay`](@ref) with the given `dmethod`, and then an optimal
 embedding dimension, by calculating an appropriate statistic for each dimension `d ∈ 1:dmax`.
 Return the embedding `𝒟`, the optimal delay time `τ`
@@ -34,7 +34,8 @@ For more details, see individual methods: [`delay_afnn`](@ref), [`delay_ifnn`](@
     you should directly calculate the statistic and plot its values versus the
     dimensions.
 
-## Keyword Arguments
+## Keyword arguments
+
 The keywords
 ```julia
 τs = 1:100, dmax = 10
@@ -51,6 +52,7 @@ w, rtol, atol, τs, metric, r
 ```
 
 ## Description
+
 We estimate the optimal embedding dimension based on the given delay time gained
 from `dmethod` as follows: For Cao's method the optimal dimension is reached,
 when the slope of the `E₁`-statistic (output from `"afnn"`) falls below the
@@ -74,7 +76,7 @@ See also the file `test/compare_different_dimension_estimations.jl` for a compar
 
 [^Hegger1999]: Hegger & Kantz, [Improved false nearest neighbor method to detect determinism in time series data. Physical Review E 60, 4970](https://doi.org/10.1103/PhysRevE.60.4970).
 """
-function optimal_traditional_de(s::AbstractVector, dimensionmethod::String = "afnn",
+function optimal_separated_de(s::AbstractVector, dimensionmethod::String = "afnn",
         delaymethod::String= "mi_min";
         fnn_thres::Real = 0.05, slope_thres::Real = .05, dmax::Int = 10, w::Int=1,
         rtol=10.0, atol=2.0, τs = 1:100, metric = Euclidean(), r::Real=2.0,
@@ -84,7 +86,6 @@ function optimal_traditional_de(s::AbstractVector, dimensionmethod::String = "af
     @assert dimensionmethod ∈ ("afnn", "fnn", "ifnn", "f1nn")
     τ = estimate_delay(s, delaymethod, τs)
     ds = 1:dmax
-    γs = ds .- 1 # TODO: This must be updated to dimension in 2.0
 
     if dimensionmethod=="afnn"
         dimension_statistic = delay_afnn(s, τ, ds; metric, w)

diff --git a/src/traditional_de/estimate_delay.jl → src/separated_de/estimate_delay.jl b/src/traditional_de/estimate_delay.jl → src/separated_de/estimate_delay.jl
diff --git a/src/traditional_de/estimate_dimension.jl → src/separated_de/estimate_dimension.jl b/src/traditional_de/estimate_dimension.jl → src/separated_de/estimate_dimension.jl
@@ -36,7 +36,7 @@ find `d` for which the value `E₁` saturates at some value around 1.
 
 `w` is the [Theiler window](@ref).
 
-See also: [`optimal_traditional_de`](@ref) and [`stochastic_indicator`](@ref).
+See also: [`optimal_separated_de`](@ref) and [`stochastic_indicator`](@ref).
 """
 function delay_afnn(s::AbstractVector{T}, τ::Int, ds = 2:6; metric=Euclidean(), w=0) where {T}
     E1s = zeros(length(ds))
@@ -153,7 +153,7 @@ The returned value is a vector with the number of FNN for each `γ ∈ γs`. The
 optimal value for `γ` is found at the point where the number of FNN approaches
 zero.
 
-See also: [`optimal_traditional_de`](@ref).
+See also: [`optimal_separated_de`](@ref).
 """
 function delay_fnn(s::AbstractVector, τ::Int, ds = 2:6; rtol=10.0, atol=2.0)
     rtol2 = rtol^2
@@ -201,7 +201,7 @@ The returned value is a vector with the ratio between the number of FFNN and
 the number of points in the dataset for each `d ∈ ds`. The optimal value for `d`
 is found at the point where this ratio approaches zero.
 
-See also: [`optimal_traditional_de`](@ref).
+See also: [`optimal_separated_de`](@ref).
 """
 function delay_f1nn(s::AbstractVector, τ::Int, ds = 2:6; metric = Euclidean())
     f1nn_ratio = zeros(length(ds))
@@ -262,7 +262,7 @@ reached.
 *`metric = Euclidean`: The norm used for distance computations.
 *`w = 1` = The [Theiler window](@ref).
 
-See also: [`optimal_traditional_de`](@ref).
+See also: [`optimal_separated_de`](@ref).
 """
 function delay_ifnn(s::AbstractVector{T}, τ::Int, ds = 1:10;
             r::Real = 2, w::Int = 1, metric = Euclidean()) where {T}