OCE efficiency (#293)

* Change defaults values

* Update docs

* Simplify

* Handle AbstractStateSpaceSet

* Create embeddings separately for every target variable

* Add Graphs support

* Prepare embeddings in separate function

* One shared function for both pairwise and conditional

* Update docstring

* Simplify source code

* Update changelog

* Update example

* New update message

* Update tests

* Split into separate functions to improve readability

* Import/export graph-related methods and types

* Update version

* Update tests

* Modify example

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.2.1"
+version = "2.3.0"
 
 [deps]
 Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"
@@ -36,7 +36,7 @@ Wavelets = "29a6e085-ba6d-5f35-a997-948ac2efa89a"
 [compat]
 Accessors = "^0.1.28"
 Combinatorics = "1"
-ComplexityMeasures = "^2.6" # contains important bugfix
+ComplexityMeasures = "^2.6"
 DSP = "0.7"
 DelayEmbeddings = "2.6"
 Distances = "^0.10"

changelog.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.3.0
+
+- Significant speed-ups for `OCE` by sorting on maximal measure, thus avoiding
+    unnecessary significance tests.
+- Default parameters for `OCE` default lag parameter have changed. Now, `τmax = 1`, since
+    that is the only case considered in the original paper. We also use the
+    `MesnerShalisi` CMI estimator for the conditional step, because in contrast to
+    the `FPVP` estimator, it has been shown to be consistent.
+- Source code for `OCE` has been drastically simplified by merging the pairwise
+    and conditional parent finding steps.
+- `OCE` result can now be converted to a `SimpleDiGraph` from Graphs.jl.
+
 ## 2.2.1
 
 - `infer_graph` now accepts the `verbose` keyword.

docs/src/examples/examples_graphs.md

@@ -8,6 +8,7 @@ for the conditional steps.
 
 ```@example causalgraph_oce
 using CausalityTools
+using Graphs
 using Random
 rng = MersenneTwister(1234)
 
@@ -16,12 +17,16 @@ sys = system(Logistic4Chain(; rng))
 x, y, z, w = columns(trajectory(sys, 400, Ttr = 10000))
 
 # Independence tests for unconditional and conditional stages.
-utest = SurrogateTest(MIShannon(), KSG2(k = 5))
-ctest = LocalPermutationTest(CMIShannon(), FPVP(k = 5))
+utest = SurrogateTest(MIShannon(), KSG2(k = 3, w = 1); rng, nshuffles = 150)
+ctest = LocalPermutationTest(CMIShannon(), MesnerShalisi(k = 3, w = 1); rng, nshuffles = 150)
 
 # Infer graph
-alg = OCE(; utest, ctest, α = 0.05, τmax = 3)
-infer_graph(alg, [x, y, z, w])
+alg = OCE(; utest, ctest, α = 0.05, τmax = 1)
+parents = infer_graph(alg, [x, y, z, w])
+
+# Convert to graph and inspect edges
+g = SimpleDiGraph(parents)
+collect(edges(g))
 ```
 
 The algorithm nicely recovers the true causal directions.

src/CausalityTools.jl

@@ -56,28 +56,19 @@ module CausalityTools
     # Update messages:
     using Scratch
     display_update = true
-    version_number = "2.0.0"
+    version_number = "2.3.0"
     update_name = "update_v$(version_number)"
     update_message = """
     \nUpdate message: CausalityTools v$(version_number)\n
-    - An overall overhaul of the API and documentation. See the online documentation
-        for a full overview.
-    - There are now three conceptual levels of funcationality: 1) association measures,
-        2) independence testing based on these measures, and 3) causal graph inference.
-
-    Other changes:
-    - A plethora of new methods and estimators for information theoretic quantities have
-        been added. See the online documentation for an overview.
-    - Syntax for many methods have changed. Estimators, which
-        also contains analysis parameters, are now always the first argument.
-    - All information-based methods in the DynamicalSystems.jl organization that are
-        more complex than those in `ComplexityMeasures.jl` have been moved to CausalityTools.jl.
-        This include `mutualinfo`, `condmutualinfo` and `transferentropy`.
-    - TransferEntropy.jl has been discontinued, and all its functionality has been moved to
-        CausalityTools.jl. `conditional_mutualinfo` has been renamed to `condmutualinfo`.
-    - The `Kraskov1` and `Kraskov2` mutual information estimators have been renamed to
-        `KraskovStögbauerGrassberger1` (`KSG1` for short) and
-        `KraskovStögbauerGrassberger2` (`KSG2` for short).
+    - Significant speed-ups for `OCE` by sorting on maximal measure, thus avoiding
+    unnecessary significance tests.
+    - Default parameters for `OCE` default lag parameter have changed. Now, `τmax = 1`, since
+        that is the only case considered in the original paper. We also use the
+        `MesnerShalisi` CMI estimator for the conditional step, because in contrast to
+        the `FPVP` estimator, it has been shown to be consistent.
+    - Source code for `OCE` has been drastically simplified by merging the pairwise
+        and conditional parent finding steps.
+    - `OCE` result can now be converted to a `SimpleDiGraph` from Graphs.jl.
     """
 
     if display_update

src/causal_graphs/causal_graphs.jl

@@ -1,3 +1,8 @@
+import Graphs.SimpleGraphs: SimpleDiGraph
+import Graphs: edges
+export SimpleDiGraph
+export edges
+
 include("api.jl")
 
 # Concrete implementations