Future features from 3.0

.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 <kahaaga@gmail.com>", "Tor Einar Møller <temolle@gmail.com>", "George Datseris <datseris.george@gmail.com>"]
 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,36 @@ 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"
+Setfield = "efcf1570-3423-57d1-acb7-fd33fddbac46"
 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"
+Setfield = "1.1.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,25 @@
 [![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
+
+- Multivariate probabilities estimation, extending the API from 
+ [ComplexityMeasures.jl](https://github.com/JuliaDynamics/ComplexityMeasures.jl).
+
 
 ## 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

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"
@@ -18,6 +17,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,73 @@
+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")
+
+ 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 = 1000 * 5^10, # 200 KiB
+ size_threshold_warn = true,
+ ),
+ sitename = "$(modules[1]).jl",
+ authors,
+ pages,
+ draft,
+ doctest = false,
+ warnonly = true,
+ checkdocs = :exported,
+ kwargs...
+ )
+
+ if isnothing(bib)
+ makedocs(; settings...)
+ else
+ makedocs(; plugins=[bib], settings...)
+ end
+
+ if CI
+ deploydocs(
+ repo = "github.com/JuliaDynamics/$(modules[1]).jl.git",
+ target = "build",
+ push_preview = true
+ )
+ end
+
+ end 

docs/make.jl

@@ -10,21 +10,42 @@ 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",
+ "Association measures" => "associations.md",
+ "Independence" => "independence.md",
+ "Network/graph inference" => "causal_graphs.md",
+ "Examples" => [
+ "Association measures" => "examples/examples_associations.md",
+ "Graph inference" => "examples/examples_infer_graphs.md",
+ "Extended examples" => [
+ "extended_examples/cross_mapping.md",
+ "extended_examples/pairwise_asymmetric_inference.md",
+ "extended_examples/mutual_information.md",
+ ],
+ #"Correlation examples" => "examples/examples_correlation.md",
+ #"Closeness examples" => "examples/examples_closeness.md",
+ #"Crossmap examples" => "examples/examples_cross_mappings.md",
+ ],
+
+ "Basics and tutorials" => [
+ "Encoding elements" => "encoding_tutorial.md",
+ "Encoding input datasets" => "discretization_tutorial.md",
+ "Counts and probabilities" => "probabilities_tutorial.md",
+ "Information measures" => "info_tutorial.md",
+
+ ],
+ # "Independence testing" => "independence.md",
+ # "Causal graphs" => "causal_graphs.md",
+ # "Predefined systems" => "coupled_systems.md",
+ # "Experimental" => "experimental.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(