Refactor api (#89)

* Remove @show

* Refactor nearest neighbors methods

* Typos

* Remove duplicate function

* Reorganize docs

* API renaming

* Switch order of docs

* Refactoring

* Unnecessary capitalization

* Further refactoring

* Missing part of equation

* Use new name

* Add deprecations

* Add note for single-symbol encoding in docstring

* Add note for single-symbol encoding in docstring

* Remove redundant note

* Use @deprecate for genentropy

* Add (preliminary) update message

* [wip] reusable docs

* re-write intro page

* improve entropy wording

* Complete re-organization of source code folders

* correct includes state

* finish first draft of docs new way (many TODOs left_)

* Fix wavelet entropy docs

* add docstrings to convenience calls

* final touches

* add documentation build phase

* Add power spectrum probability estimator (#94)

* add code and docstring for spectral entropy

* add docs

* even better test reorganization

* add one more depth level

* WIP: reviewing new api (#95)

* Equivalent to, not equivalent with

* Include dispersion entropy

* Clearer wording

* Symbolization routines need to be imported before estimators using them

* Export in-place version.

* Follow Julia's linting conventions

* Run CI on all pull requests

* Don't export in-place version

* Missing a letter

Co-authored-by: Datseris <[email protected]>

Author: kahaaga

.github/workflows/ci.yml

@@ -3,6 +3,7 @@ on:
   pull_request:
     branches:
       - main
+      - '**' # matches every branch
   push:
     branches:
       - main
@@ -15,20 +16,18 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1' # Replace this with the minimum Julia version that your package supports. E.g. if your package requires Julia 1.5 or higher, change this to '1.5'.
-        os:
-          - ubuntu-latest
+          - '1'
+        os:  [ubuntu-latest] # adjust according to need, e.g. os: [ubuntu-latest] if testing only on linux
         arch:
           - x64
-
     steps:
-      # Cancel ongoing CI test runs if pushing to branch again before the previous tests 
+      # 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/[email protected]
         with:
           access_token: ${{ github.token }}
-      
+
       # Do tests
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@v1
@@ -51,3 +50,31 @@ jobs:
       - uses: codecov/codecov-action@v1
         with:
           file: lcov.info
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      # Cancel ongoing documentation build if pushing to branch again before the previous
+      # build is finished.
+      - name: Cancel ongoing documentation builds for previous commits
+        uses: styfle/[email protected]
+        with:
+          access_token: ${{ github.token }}
+
+      # Build docs
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - name: Instantiate and install dependencies
+        run: |
+          julia --project=docs -e '
+              using Pkg
+              Pkg.develop(PackageSpec(path=pwd()))
+              Pkg.instantiate()'
+      - name: Generate documentation and deploy
+        env: # needed for pushing to gh-pages branch
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+        run:
+          julia --project=docs docs/make.jl

Project.toml

@@ -7,10 +7,12 @@ version = "1.3.0"
 [deps]
 DelayEmbeddings = "5732040d-69e3-5649-938a-b6b4f237613f"
 Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
+FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Neighborhood = "645ca80c-8b79-4109-87ea-e1f58159d116"
 QuadGK = "1fd47b50-473d-5c70-9696-f719f8f3bcdc"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Scratch = "6c6a2e73-6563-6170-7368-637461726353"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
@@ -21,8 +23,10 @@ Wavelets = "29a6e085-ba6d-5f35-a997-948ac2efa89a"
 [compat]
 DelayEmbeddings = "2"
 Distances = "0.9, 0.10"
+FFTW = "1"
 Neighborhood = "0.1, 0.2"
 QuadGK = "2"
+Scratch = "1"
 SpecialFunctions = "0.10, 1.0, 2"
 StaticArrays = "0.12, 1.0"
 StatsBase = "0.33"

docs/Project.toml

@@ -5,7 +5,7 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
 DynamicalSystems = "61744808-ddfa-5f27-97ff-6e42cc95d634"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+Entropies = "ed8fcbec-b94c-44b6-89df-898894ad9591"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
-Wavelets = "29a6e085-ba6d-5f35-a997-948ac2efa89a"

docs/make.jl

@@ -1,22 +1,26 @@
+using Entropies # using before activation of environment ensures dev'ed version
 cd(@__DIR__)
 using Pkg
 CI = get(ENV, "CI", nothing) == "true" || get(ENV, "GITHUB_TOKEN", nothing) !== nothing
-CI && Pkg.activate(@__DIR__)
+Pkg.activate(@__DIR__)
 CI && Pkg.instantiate()
-CI && (ENV["GKSwstype"] = "100")
 using DelayEmbeddings
 using Documenter
 using DocumenterTools: Themes
-using Entropies
-using PyPlot
+using CairoMakie
+using Entropies.Wavelets
 using DynamicalSystems
-using Wavelets
 
-# %% JuliaDynamics theme.
-# download the themes
+# %% JuliaDynamics theme
+# It includes themeing for the HTML build
+# and themeing for the Makie plotting
+
 using DocumenterTools: Themes
 for file in ("juliadynamics-lightdefs.scss", "juliadynamics-darkdefs.scss", "juliadynamics-style.scss")
-    download("https://raw.githubusercontent.com/JuliaDynamics/doctheme/master/$file", joinpath(@__DIR__, file))
+    filepath = joinpath(@__DIR__, file)
+    if !isfile(filepath)
+        download("https://raw.githubusercontent.com/JuliaDynamics/doctheme/master/$file", joinpath(@__DIR__, file))
+    end
 end
 # create the themes
 for w in ("light", "dark")
@@ -29,18 +33,10 @@ Themes.compile(joinpath(@__DIR__, "juliadynamics-light.scss"), joinpath(@__DIR__
 Themes.compile(joinpath(@__DIR__, "juliadynamics-dark.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-dark.css"))
 
 # %% Build docs
-PyPlot.ioff()
-cd(@__DIR__)
 ENV["JULIA_DEBUG"] = "Documenter"
 
-PAGES = [
-    "Entropies.jl" => "index.md",
-    "Estimators" => "estimators.md",
-    "Remaining" => [
-        "DispersionEntropy.md",
-    ],
-    "Utility methods" => "utils.md",
-]
+PAGES = include("toc.jl")
+include("style.jl")
 
 makedocs(
     modules = [Entropies],
@@ -49,6 +45,7 @@ makedocs(
         assets = [
             asset("https://fonts.googleapis.com/css?family=Montserrat|Source+Code+Pro&display=swap", class=:css),
         ],
+        collapselevel = 3,
         ),
     sitename = "Entropies.jl",
     authors = "Kristian Agasøster Haaga, George Datseris",
@@ -62,5 +59,3 @@ if CI
         push_preview = true
     )
 end
-PyPlot.close("all")
-PyPlot.ion()

docs/src/DispersionEntropy.md

@@ -0,0 +1,7 @@
+# Complexity measures
+
+## Sample entropy
+
+## Approximate entropy
+
+## Disequilibrium

docs/src/complexity_measures.md

@@ -0,0 +1,36 @@
+# Entropies
+
+## Rényi (generalized) entropy
+
+```@docs
+entropy_renyi
+```
+
+## Tsallis (generalized) entropy
+
+```@docs
+entropy_tsallis
+```
+
+## Shannon entropy (convenience)
+```@docs
+entropy_shannon
+```
+
+## Indirect entropies
+Here we list functions which compute Shannon entropies via alternate means, without explicitly computing some probability distributions and then using the Shannon formulat.
+
+### Nearest neighbors entropy
+```@docs
+entropy_kraskov
+entropy_kozachenkoleonenko
+```
+
+## Convenience functions
+In this subsection we expand documentation strings of "entropy names" that are used commonly in the literature, such as "permutation entropy". As we made clear in [API & terminology](@ref), these are just the existing Shannon/Rényi/Tsallis entropy with a particularly chosen probability estimator. We have only defined convenience functions for the most used names, and arbitrary more specialized convenience functions can be easily defined in a couple lines of code.
+```@docs
+entropy_permutation
+entropy_spatial_permutation
+entropy_wavelet
+entropy_dispersion
+```