V3: complete overhaul

.github/workflows/CompatHelper.yml

@@ -2,7 +2,7 @@ name: CompatHelper
 
 on:
   schedule:
-    - cron: '00 * * * *'
+    - cron: '00 8 * * *'
 
 jobs:
   CompatHelper:

.gitignore

@@ -12,3 +12,4 @@ Manifest.toml
 *.scss
 *.css
 vscode/*
+*.cov

Project.toml

@@ -2,7 +2,7 @@ name = "CausalityTools"
 uuid = "5520caf5-2dd7-5c5d-bfcb-a00e56ac49f7"
 authors = ["Kristian Agasøster Haaga <[email protected]>", "Tor Einar Møller <[email protected]>", "George Datseris <[email protected]>"]
 repo = "https://github.com/kahaaga/CausalityTools.jl.git"
-version = "2.10.1"
+version = "3.0.0"
 
 [deps]
 Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"
@@ -12,10 +12,9 @@ DSP = "717857b8-e6f2-59f4-9121-6e50c889abd2"
 DelayEmbeddings = "5732040d-69e3-5649-938a-b6b4f237613f"
 Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
-DynamicalSystemsBase = "6e36e845-645a-534a-86f2-f5d4aa5a06b4"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 HypothesisTests = "09f84164-cd44-5f33-b23f-e6b0d136a0d5"
-LabelledArrays = "2ee39098-c373-598a-b85f-a56591580800"
+LaTeXStrings = "b964fa9f-0449-5b57-a5c2-d3ea65f4040f"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 NearestNeighbors = "b8a86587-4115-5ab1-83bc-aa920d37bbce"
 Neighborhood = "645ca80c-8b79-4109-87ea-e1f58159d116"
@@ -24,37 +23,34 @@ Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 RecurrenceAnalysis = "639c3291-70d9-5ea2-8c5b-839eba1ee399"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 Scratch = "6c6a2e73-6563-6170-7368-637461726353"
-SimpleDiffEq = "05bca326-078c-5bf0-a5bf-ce7c7982d7fd"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 StateSpaceSets = "40b095a5-5852-4c12-98c7-d43bf788e795"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+StyledStrings = "f489334b-da3d-4c2e-b8f0-e476e12c162b"
 TimeseriesSurrogates = "c804724b-8c18-5caa-8579-6025a0767c70"
 
 [compat]
 Accessors = "^0.1.28"
 Combinatorics = "1"
-ComplexityMeasures = "2 - 2.8"
-DSP = "0.7"
+ComplexityMeasures = "3.6.5"
+DSP = "^0.7"
 DelayEmbeddings = "2.7"
 Distances = "^0.10"
-Distributions = "^0.24, 0.25"
-DynamicalSystemsBase = "3"
+Distributions = "^0.25"
 Graphs = "^1.8"
-HypothesisTests = "0.8, 1, 0.10, 0.11"
-LabelledArrays = "1.6.7"
-NearestNeighbors = "0.4"
-Neighborhood = "0.2.2"
+HypothesisTests = "^0.11"
+NearestNeighbors = "^0.4"
+Neighborhood = "^0.2.4"
 ProgressMeter = "1.7"
 RecurrenceAnalysis = "2"
-Reexport = "0.2, 1"
+Reexport = "1"
 Scratch = "1"
-SimpleDiffEq = "^1"
 SpecialFunctions = "2"
-StateSpaceSets = "^1.4"
+StateSpaceSets = "^1.5"
 StaticArrays = "^1"
-StatsBase = "^0.33, 0.34"
-TimeseriesSurrogates = "2.5"
-julia = "^1.6"
+StatsBase = "^0.34"
+StyledStrings = "1"
+TimeseriesSurrogates = "2.6"
+julia = "^1.10"

README.md

@@ -6,25 +6,28 @@
 [![codecov](https://codecov.io/gh/JuliaDynamics/CausalityTools.jl/branch/master/graph/badge.svg?token=0b71n6x6AP)](https://codecov.io/gh/JuliaDynamics/CausalityTools.jl)
 [![DOI](https://zenodo.org/badge/135443027.svg)](https://zenodo.org/badge/latestdoi/135443027)
 
-CausalityTools.jl is a package for quantifying associations and dynamical coupling
-between datasets, independence testing and causal inference.
+CausalityTools.jl is a package for quantifying associations, independence testing and causal inference.
 
 All further information is provided in the
 [documentation](https://juliadynamics.github.io/CausalityTools.jl/dev), which you can either
 find online or build locally by running the `docs/make.jl` file.
 
 ## Key features
 
-- Association measures from conventional statistics, information theory and dynamical
-    systems theory, for example distance correlation, mutual information, transfer entropy,
-    convergent cross mapping and a lot more!
-- A dedicated API for independence testing, which comes with automatic compatibility with
-    every measure-estimator combination you can think of. For example, we offer the generic
-    `SurrogateTest`, which is fully compatible with
-    [TimeseriesSurrogates.jl](https://github.com/JuliaDynamics/TimeseriesSurrogates.jl),
-    and the `LocalPermutationTest` for conditional indepencence testing.
-- A dedicated API for causal network inference based on these measures and independence
-    tests.
+- **Association API**: includes measures and their estimators for pairwise, conditional and other forms of 
+    association from conventional statistics, from dynamical systems theory, and from information theory: partial correlation, distance correlation, (conditional) mutual information, transfer entropy, convergent cross mapping and a lot more!
+- **Independence testing API**, which is automatically compatible with
+    every association measure estimator implemented in the package. 
+- **Causal (network) inference API** integrating the association measures and independence testing framework.
+
+## Addititional features
+
+Extending on features from [ComplexityMeasures.jl](https://github.com/JuliaDynamics/ComplexityMeasures.jl),
+we also offer 
+
+- Discretization API for multiple (multivariate) input datasets.
+- Multivariate counting and probability estimation API.
+- Multivariate information measure API
 
 ## Installation
 

changelog.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 3.0 (new major release)
+
+This release contains several breaking changes. Any code from before v3.0 will need 
+updating to continue working with v3.0.
+
+The main reason for these breaking changes is that estimators now store the 
+definitions they estimate. This way, we reduce the amount of code we have to write 
+maintain, document and test. At the same time, we hope it is a bit more user-friendly 
+to only relate to "one way of thinking" about estimating association measures.
+
+### Breaking changes 
+
+#### Association measures
+
+- The function `association(measure_or_est, input_data...)` is the central function that computes 
+    all association measures. The first argument is either a measure definition (if it has no 
+    estimator), or an estimator. This means that if `input_data` consists of two input datasets, 
+    then a pairwise association is estimated. If `input_data` consists of three input datasets, then typically a conditional association is estimated (but exceptions are possible).
+
+#### Independence testing 
+
+- `SurrogateTest` is now `SurrogateAssociationTest`
+- `SurrogateTestResult` is now `SurrogateAssociationTestResult`
+
+#### Example systems 
+
+- All example systems are removed.
+
+#### Crossmap API
+
+The crossmap API has been overhauled. 
+
+- `CrossmapEstimator`s now take the `CrossmapMeasure` definition as their first argument.
+    For example, you'll have to do `ExpandingSegment(CCM(); libsizes = 10:10:50)` instead
+    of `ExpandingSegment(; libsizes = 10:10:50)`.
+
+#### Information API
+
+The information API has been overhauled.
+
+- Multivariate information measures now store their parameters explicitly, instead 
+    of using `ComplexityMeasures.EntropyDefinition` to do so. For example, to 
+    define Shannon-type conditional mutual information, one should do 
+    `CMIShannon(base = 2)` instead of `CMIShannon(Shannon(base = 2))`.
+- New generic discrete estimator `JointDistribution` for estimating multivariate
+    information measures. This estimators explicitly computes the joint distribution
+    based on the given discretization, and can be applied to any measure which is 
+    defined as a function of a joint distribution.
+- New generic decomposition-based estimator `EntropyDecomposition`. This estimator
+    computes some multivariate information measure by rewriting the measure definition
+    as a combination of some lower-level measure. For example, `CMIShannon` can be 
+    rewritten as a sum of `Shannon` entropies. Each of these terms can then 
+    be estimated using some differential entropy estimator, e.g. `ZhuSingh` or `Kraskov`.
+- New generic decomposition-based estimator `MIDecomposition`. This estimator
+    computes some multivariate information measure by rewriting the measure definition
+    as a combination of some mutual information measure.
+- New generic decomposition-based estimator `CMIDecomposition`. This estimator
+    computes some multivariate information measure by rewriting the measure definition
+    as a combination of some conditional mutual information measure.
+
+### Bux fixes
+
+- There was an error in the implementation of `PartMutualInformation`. It is now fixed using explicit loops for computing the measures from a probability distribution.
+
+
 ## 2.10
 
 - Progress bars in some independence tests (surrogate, local permutation) can be
@@ -78,7 +143,7 @@ indices).
 - Bugfix for `OCE` for certain conditional variable cases.
 - Improve docstring for `OCE`.
 - Updated readme.
-- Fixed bug related to `DifferentialEntropyEstimator` "unit" conversion.
+- Fixed bug related to `DifferentialInfoEstimator` "unit" conversion.
 
 ## 2.0
 

docs/Project.toml

@@ -1,5 +1,4 @@
 [deps]
-BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 CausalityTools = "5520caf5-2dd7-5c5d-bfcb-a00e56ac49f7"
 ComplexityMeasures = "ab4b797d-85ee-42ba-b621-05d793b346a2"
@@ -8,6 +7,7 @@ Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
 DynamicalSystemsBase = "6e36e845-645a-534a-86f2-f5d4aa5a06b4"
 GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
@@ -18,6 +18,7 @@ LabelledArrays = "2ee39098-c373-598a-b85f-a56591580800"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 StateSpaceSets = "40b095a5-5852-4c12-98c7-d43bf788e795"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"

docs/build_docs_with_style.jl

@@ -0,0 +1,94 @@
+CI = get(ENV, "CI", nothing) == "true" || get(ENV, "GITHUB_TOKEN", nothing) !== nothing
+
+ import Pkg
+ Pkg.pkg"add Documenter@1"
+
+ # Load documenter
+ using Documenter
+ using DocumenterTools: Themes
+ ENV["JULIA_DEBUG"] = "Documenter"
+
+ # For easier debugging when downloading from a specific branch.
+ github_user = "JuliaDynamics"
+ branch = "master"
+ download_path = "https://raw.githubusercontent.com/$github_user/doctheme/$branch"
+
+ import Downloads
+ for file in ("juliadynamics-lightdefs.scss", "juliadynamics-darkdefs.scss", "juliadynamics-style.scss")
+     Downloads.download("$download_path/$file", joinpath(@__DIR__, file))
+ end
+
+ # create the themes
+ for w in ("light", "dark")
+     header = read(joinpath(@__DIR__, "juliadynamics-style.scss"), String)
+     theme = read(joinpath(@__DIR__, "juliadynamics-$(w)defs.scss"), String)
+     write(joinpath(@__DIR__, "juliadynamics-$(w).scss"), header*"\n"*theme)
+ end
+
+ # compile the themes
+ Themes.compile(joinpath(@__DIR__, "juliadynamics-light.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-light.css"))
+ Themes.compile(joinpath(@__DIR__, "juliadynamics-dark.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-dark.css"))
+
+ # Download and apply CairoMakie plotting style
+ using CairoMakie
+ Downloads.download("$download_path/style.jl", joinpath(@__DIR__, "style.jl"))
+ include("style.jl")
+
+ using DocumenterInterLinks
+
+links = InterLinks(
+    "ComplexityMeasures" => (
+        "https://juliadynamics.github.io/DynamicalSystemsDocs.jl/complexitymeasures/stable/",
+        "https://juliadynamics.github.io/DynamicalSystemsDocs.jl/complexitymeasures/stable/objects.inv",
+        joinpath(@__DIR__, "inventories", "Documenter.toml")
+    ),
+    "StateSpaceSets" => (
+        "https://juliadynamics.github.io/DynamicalSystemsDocs.jl/statespacesets/stable/",
+        "https://juliadynamics.github.io/DynamicalSystemsDocs.jl/statespacesets/stable/objects.inv",
+        joinpath(@__DIR__, "inventories", "Documenter.toml")
+    ),
+);
+
+ function build_docs_with_style(pages, modules...; bib = nothing, authors = "George Datseris", draft = false, kwargs...)
+     settings = (
+         modules = [modules...],
+         format = Documenter.HTML(
+             prettyurls = CI,
+             assets = [
+                 asset("https://fonts.googleapis.com/css?family=Montserrat|Source+Code+Pro&display=swap", class=:css),
+             ],
+             collapselevel = 3,
+             size_threshold = 1250 * 2^10, 
+             size_threshold_warn = 750 * 2^10,
+             example_size_threshold = 100 * 2^10,
+             size_threshold_ignore = [
+                "examples/examples_associations.md", 
+                "examples/examples_independence.md",
+                "examples/examples_infer_graphs.md",
+             ]
+         ),
+         sitename = "$(modules[1]).jl",
+         authors,
+         pages,
+         draft,
+         doctest = false,
+         warnonly = false,
+         checkdocs = :exported,
+         kwargs...
+     )
+
+     if isnothing(bib)
+         makedocs(; settings...)
+     else
+         makedocs(; plugins=[bib, links], settings...)
+     end
+
+     if CI
+         deploydocs(
+             repo = "github.com/JuliaDynamics/$(modules[1]).jl.git",
+             target = "build",
+             push_preview = true
+         )
+     end
+
+ end 

docs/make.jl

@@ -2,6 +2,7 @@ cd(@__DIR__)
 # Doc-specific (remaining packages are imported  in `build_docs_with_style.jl`, which is
 # downloaded)
 using DocumenterCitations
+using DocumenterInterLinks
 import Downloads
 
 # Packages used in the doc build.
@@ -10,21 +11,31 @@ using ComplexityMeasures
 using StateSpaceSets
 
 pages = [
-    "Overview" => "index.md",
-    "Association measures" => "measures.md",
-    "Independence testing" => "independence.md",
-    "Causal graphs" => "causal_graphs.md",
-    "APIs and estimators" => "api.md",
-    "Examples" => "examples.md",
-    "Predefined systems" => "coupled_systems.md",
-    "Experimental" => "experimental.md",
+    "CausalityTools.jl" => "index.md",
+    "Core API reference" => [
+        "Association measures" => "associations.md",
+        "Independence" => "independence.md",
+        "Network/graph inference" => "causal_graphs.md",
+    ],
+    "Extended API reference" => [
+        "api/discretization_counts_probs_api.md",
+        "api/counts_and_probabilities_api.md",
+        "api/information_single_variable_api.md",
+        "api/information_multivariate_api.md",
+        "api/cross_map_api.md",
+    ],
+    "Examples" => [
+        "Associations" => "examples/examples_associations.md", 
+        "Independence testing" => "examples/examples_independence.md",
+        "Causal graph inference" => "examples/examples_infer_graphs.md",
+    ],
     "References" => "references.md",
 ]
 
-Downloads.download(
-    "https://raw.githubusercontent.com/JuliaDynamics/doctheme/master/build_docs_with_style.jl",
-    joinpath(@__DIR__, "build_docs_with_style.jl")
-)
+# Downloads.download(
+#     "https://raw.githubusercontent.com/JuliaDynamics/doctheme/master/build_docs_with_style.jl",
+#     joinpath(@__DIR__, "build_docs_with_style.jl")
+# )
 include("build_docs_with_style.jl")
 
 bibliography = CitationBibliography(