Release 0.9.1 (#99)

- Make sure all internals use the same notation for the time series (`source`, `target` and `cond` instead of `x`, `y` and `z`). - Major documentation restructuring/improvements.
JuliaDynamics · Dec 25, 2019 · 1162f6d · 1162f6d
1 parent 3ca9c6c
commit 1162f6d
Show file tree

Hide file tree

Showing 42 changed files with 587 additions and 207 deletions.
diff --git a/Project.toml b/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]>"]
 repo = "https://github.com/kahaaga/CausalityTools.jl.git"
-version = "0.9.0"
+version = "0.9.1"
 
 [deps]
 CausalityToolsBase = "b1f25513-c649-51ee-8a1c-0e98d01ae897"
@@ -51,7 +51,7 @@ StateSpaceReconstruction = "^0.4.2, ^1"
 StaticArrays = "^0.11.0, ^1"
 StatsBase = "^0.32.0, ^1"
 TimeseriesSurrogates = "^0.5.1, ^1"
-TransferEntropy = "^0.5.4, ^1"
+TransferEntropy = "^0.5.6, ^1"
 UncertainData = "^0.10"
 julia = "^1.1"
 

diff --git a/docs/make.jl b/docs/make.jl
@@ -21,13 +21,12 @@ using UncertainData
 ENV["GKSwstype"] = "100"
 
 PAGES = [
-    "index.md",
+    #"index.md",
+    #"FAQ.md",
+    "overview.md",
     "Syntax overview" => "syntax_overview.md",
     "CHANGELOG.md",
     "Causality tests" => [
-        # From time series
-        "causalitytests/causality_from_time_series.md",
-
         # From uncertain data
         "causalitytests/causality_from_uncertain_data_naive.md",
         "causalitytests/causality_from_uncertain_data_binneddatacausalitytest.md",
@@ -42,7 +41,8 @@ PAGES = [
 
         # Tests
         "causalitytests/causality_tests.md",
-
+        "causalitytests/abstract_test_types.md",
+        "causalitytests/causality_tests_overview.md",
         "causalitytests/ConvergentCrossMappingTest.md",
         "causalitytests/CrossMappingTest.md",
         "causalitytests/JointDistanceDistributionTest.md",
@@ -71,17 +71,28 @@ PAGES = [
         "Convenience methods" => "transferentropy/convenience_methods_te.md",
         "Effect of discretization scheme" => "transferentropy/examples_TE_different_partitionings.md",
     ],
-    "Distance based measures" => [
+    "Distance based statistics" => [
         "CCM" => [
             "Overview" => "crossmappings/ccm/overview.md",
             "Cross mapping" => "crossmappings/ccm/crossmapping.md",
             "Converent cross mapping" => "crossmappings/ccm/convergentcrossmapping.md"
-        ], 
-        "Joint distance distribution" => "algorithms/joint_distance_distribution.md"
+        ]
+    ],
+
+    "Joint distance distribution" => [
+        "JointDistanceDistribution/joint_distance_distribution.md"
+    ],
+
+    "SMeasure" => [
+        "S-measure" => "SMeasure/s_measure.md"
     ],
     "Worked example" => [
         "worked_examples/worked_example_transferentropy.md"
     ],
+
+    "Simplices" => [
+        "simplices/Simplices.md"
+    ],
 
     "Example systems" => [
         "example_systems/noise.md",
@@ -115,7 +126,7 @@ PAGES = [
 makedocs(
     sitename = "CausalityTools.jl documentation",
     #modules = [CausalityTools, TransferEntropy, PerronFrobenius, CrossMappings, CausalityToolsBase, UncertainData],
-    modules = [CausalityTools, TransferEntropy, PerronFrobenius, CrossMappings, CausalityToolsBase, UncertainData],
+    modules = [CausalityTools, TransferEntropy, PerronFrobenius, CrossMappings, CausalityToolsBase, UncertainData, Simplices],
     format = DocumenterMarkdown.Markdown(),
     linkcheck = false,
     clean = true,

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -37,39 +37,45 @@ markdown_extensions:
 docs_dir: 'build'
 
 pages:
-  - Home: index.md
-  - Causality estimation:
-    - From time series: causalitytests/causality_from_time_series.md
-    - From uncertain time series: 
-      - Methods: causalitytests/causality_from_uncertain_data.md
+  - Introduction and contents: index.md
+  #- Overview:
+  #- FAQ: FAQ.md
+  #- Package overview: overview.md
+  #- Syntax overview: syntax_overview.md
+  - Estimating causality:
+    - From scalar time series: causalitytests/causality_tests.md
+    - From uncertain time series: causalitytests/causality_from_uncertain_data_naive.md
     - From dynamical systems: causalitytests/causality_from_dynamical_systems.md
   - Causality tests: 
-    - Overview: causalitytests/causality_tests.md
-    - Cross mappings:
-      - CrossMappingTest: causalitytests/CrossMappingTest.md
-      - ConvergentCrossMappingTest: causalitytests/ConvergentCrossMappingTest.md
-    - Distance based:
-      - JointDistanceDistributionTest: causalitytests/JointDistanceDistributionTest.md
-      - SMeasureTest: causalitytests/SMeasureTest.md
-    - Transfer entropy:
-      - TransferOperatorGridTest: causalitytests/TransferOperatorGridTest.md
-      - VisitationFrequencyTest: causalitytests/VisitationFrequencyTest.md
-      - NearestNeighbourMITest: causalitytests/NearestNeighbourMITest.md
-      - ApproximateSimplexIntersectionTest: causalitytests/ApproximateSimplexIntersectionTest.md
-      - ExactSimplexIntersectionTest: causalitytests/ExactSimplexIntersectionTest.md
-    - Predictive asymmetry:
-      - PredictiveAsymmetryTest: causalitytests/PredictiveAsymmetryTest.md
-      - NormalisedPredictiveAsymmetryTest: causalitytests/NormalisedPredictiveAsymmetryTest.md
-  - Uncertainty handling and subsampling:
-      - Naive resampling: causalitytests/causality_from_uncertain_data_naive.md
-      - ConstrainedTest: causalitytests/causality_from_uncertain_data_naive_constrained.md
-      - BinnedDataCausalityTest: causalitytests/causality_from_uncertain_data_binneddatacausalitytest.md
-      - InterpolateBinTest: causalitytests/causality_from_uncertain_data_InterpolateBinTest.md
-      - RandomSequencesTest: causalitytests/causality_from_uncertain_data_RandomSequencesTest.md
-      - Strictly increasing and interpolated resampling: causalitytests/causality_from_uncertain_data_strictlyincreasing_interpolated.md
+    - Overview: causalitytests/causality_tests_overview.md
+    - Tests:
+      - Cross mappings:
+        - CrossMappingTest: causalitytests/CrossMappingTest.md
+        - ConvergentCrossMappingTest: causalitytests/ConvergentCrossMappingTest.md
+      - Distance based:
+        - JointDistanceDistributionTest: causalitytests/JointDistanceDistributionTest.md
+        - SMeasureTest: causalitytests/SMeasureTest.md
+      - Transfer entropy:
+        - TransferOperatorGridTest: causalitytests/TransferOperatorGridTest.md
+        - VisitationFrequencyTest: causalitytests/VisitationFrequencyTest.md
+        - NearestNeighbourMITest: causalitytests/NearestNeighbourMITest.md
+        - ApproximateSimplexIntersectionTest: causalitytests/ApproximateSimplexIntersectionTest.md
+        - ExactSimplexIntersectionTest: causalitytests/ExactSimplexIntersectionTest.md
+      - Predictive asymmetry:
+        - PredictiveAsymmetryTest: causalitytests/PredictiveAsymmetryTest.md
+        - NormalisedPredictiveAsymmetryTest: causalitytests/NormalisedPredictiveAsymmetryTest.md
+      - Abstract test types: causalitytests/abstract_test_types.md
+    - Meta-tests for uncertainty handling and subsampling:
+        - Overview: causalitytests/causality_from_uncertain_data.md
+        - BinnedDataCausalityTest: causalitytests/causality_from_uncertain_data_binneddatacausalitytest.md
+        - ConstrainedTest: causalitytests/causality_from_uncertain_data_naive_constrained.md
+        - InterpolateBinTest: causalitytests/causality_from_uncertain_data_InterpolateBinTest.md
+        - RandomSequencesTest: causalitytests/causality_from_uncertain_data_RandomSequencesTest.md
+        - Strictly increasing and interpolated resampling: causalitytests/causality_from_uncertain_data_strictlyincreasing_interpolated.md
   - CausalityToolsBase:
+    - Generalised delay reconstructions: causalitytoolsbase/delay_reconstructions.md
     - Discretization: causalitytoolsbase/discretization.md
-    - Delay reconstruction: causalitytoolsbase/delay_reconstructions.md
+  - Simplices: simplices/Simplices.md
   - PerronFrobenius:
       - Invariant measure: perronfrobenius/invariantmeasure.md
       - Transfer operator: perronfrobenius/transferoperator.md
@@ -83,26 +89,25 @@ pages:
     - Overview: crossmappings/ccm/overview.md
     - Cross mapping: crossmappings/ccm/crossmapping.md
     - Converent cross mapping: crossmappings/ccm/convergentcrossmapping.md
-  - Joint distance distribution: algorithms/joint_distance_distribution.md
-  - Syntax overview: syntax_overview.md
+  - S-measure: SMeasure/s_measure.md
+  - Joint distance distribution: JointDistanceDistribution/joint_distance_distribution.md
+  - TimeseriesSurrogates:
+    - Overview: surrogates/surrogates_overview.md
+    - IAAFT: surrogates/iaaft_docs.md
+    - AAFT: surrogates/aaft_docs.md
+    - Fourier surrogates, random phases: surrogates/randomphases_docs.md
+    - Fourier surrogates, random amplitudes: surrogates/randomamplitudes_docs.md
+    - Random shuffle: surrogates/randomshuffle_docs.md
   - Example systems: 
     - Overview: example_systems/example_systems_overview.md
     - Discrete systems: example_systems/example_systems_discrete.md
     - Continuous systems: example_systems/example_systems_continuous.md
     - Noise processes: example_systems/noise.md
-  - Surrogate data:
-    - Overview: surrogates/surrogates_overview.md
-    - Methods:
-      - IAAFT: surrogates/iaaft_docs.md
-      - AAFT: surrogates/aaft_docs.md
-      - Fourier surrogates, random phases: surrogates/randomphases_docs.md
-      - Fourier surrogates, random amplitudes: surrogates/randomamplitudes_docs.md
-      - Random shuffle: surrogates/randomshuffle_docs.md
   - Tutorials/examples: 
     - List of tutorials: tutorials/list_of_tutorials.md
-    - Causality from scalar data:
+    - Causality from scalar time series:
       - SMeasureTest: tutorials/causality/tutorial_SMeasureTest.md
-    - Causality from uncertain data:
+    - Causality from uncertain time series:
       - BinnedResampling + RandomSequencesTest: tutorials/causality/Tutorial_BinnedResampling_RandomSequencesTest_PredictiveAsymmetryTest_ar1_unidir.md
       - BinnedResampling: tutorials/causality/binned_uncertain_data/tutorial_BinnedDataCausalityTest_PredictiveAsymmetryTest_BinnedResampling.md
       - BinnedMeanResampling: tutorials/causality/binned_uncertain_data/tutorial_BinnedDataCausalityTest_PredictiveAsymmetryTest_BinnedMeanResampling.md

diff --git a/docs/src/CHANGELOG.md b/docs/src/CHANGELOG.md
@@ -1,5 +1,21 @@
 # Changelog for CausalityTools.jl
 
+## Release v0.9.1
+
+### Documentation
+
+- Figures in `PredictiveAsymmetryTest` example are now larger.
+- [`NearestNeighbourMITest`])(@ref) and [`NormalisedPredictiveAsymmetryTest`](@ref) added to documentation
+    for [`EntropyBasedCausalityTest`](@ref).
+- Documentation for transfer entropy estimators updated with references to where they are applicable.
+- Enlarged some figures.
+- Improved tutorial for `SMeasureTest`.
+
+### Non-breaking changes
+
+- Make sure all methods use `source`, `target` and `cond` internally (instead of `x`, `y`, and `z`). 
+    These have clearer meanings.
+
 ## Release v0.9.0
 
 Release v0.9.0 introduces some new functionality and significant documentation improvements.

diff --git a/docs/src/FAQ.md b/docs/src/FAQ.md
@@ -0,0 +1,39 @@
+# [FAQ](@id FAQ)
+
+## I want to see an overview of available causality tests
+
+See the [package overview](@ref package_overview).
+
+## I want to use low-level methods directly
+
+### Transfer entropy
+
+- I want to understand how [marginals are assigned](@ref te_assigning_marginals) during transfer entropy computations.
+- [`transferentropy(::Any, ::TEVars, ::RectangularBinning, ::BinningTransferEntropyEstimator)`](@ref) for estimating transfer entropy by discretizing the [state space reconstruction](@ref custom_delay_reconstruction) of your data into a rectangular grid.
+- [`transferentropy(::Any, ::TEVars, ::NearestNeighbourMI)`](@ref) for estimating transfer entropy by counting nearest neighbours in [state space reconstruction](@ref custom_delay_reconstruction) of your data.
+- [`transferentropy(::Any, ::TEVars, ::RectangularBinning, ::BinningTransferEntropyEstimator)`](@ref) for estimating transfer entropy by discretizing the [state space reconstruction](@ref custom_delay_reconstruction) of your data into a triangular partition.
+
+### Joint distance distribution
+
+- [`joint_distance_distribution(source, target)`](@ref) computes the joint distance distribution over a set of subintervals.
+- [`joint_distance_distribution(test::OneSampleTTest, source, target)`](@ref) computes the joint distance distribution over a set of subintervals and returns a t-test for the distribution.
+
+## Cross mappings
+
+- [`crossmap(driver, response)`](@ref) computes cross mapping skills for a given library size.
+- [`convergentcrossmap(driver, response, timeseries_lengths)`](@ref) computes cross mapping skills for a given library size, but over multiple time series lengths.
+
+## Regular time series
+
+I have regular time series want to see a tuturial on a specific causality detection method:
+
+- [`SMeasureTest` tutorial](@ref tutorial_SMeasureMest).
+
+## Time series with uncertainties
+
+My data have uncertainties in time indices (and potentially values). I want to use the
+built-in uncertainty handling tools to compute a causality statitistic for my data.
+
+### Estimating causality statistics on binned data
+
+- [PredictiveAsymmetryTest](@ref tutorial_PredictiveAsymmetryTest_BinnedMeanResampling).
diff --git a/...algorithms/joint_distance_distribution.md → ...stribution/joint_distance_distribution.md b/...algorithms/joint_distance_distribution.md → ...stribution/joint_distance_distribution.md
@@ -1,5 +1,5 @@
 
-## Distribution of joint distances
+# [Distribution of joint distances](@id joint_distance_distribution_overview)
 
 ```@docs
 joint_distance_distribution(::Any, ::Any)

diff --git a/docs/src/SMeasure/s_measure.md b/docs/src/SMeasure/s_measure.md
@@ -0,0 +1,5 @@
+# [S-measure](@id Smeasure_overview)
+
+```@docs
+s_measure
+```
diff --git a/docs/src/algorithms/s_measure.md b/docs/src/algorithms/s_measure.md
diff --git a/docs/src/causalitytests/PredictiveAsymmetryTest.md b/docs/src/causalitytests/PredictiveAsymmetryTest.md
@@ -35,7 +35,7 @@ npts = 200
 sys = CausalityTools.Systems.logistic2_unidir(c_xy = 0.5)
 x, y = columns(trajectory(sys, npts, Ttr = 500)) # discard first 500 points
 
-plot(xlabel = "Time step", ylabel = "Value", size = (382, 150),
+plot(xlabel = "Time step", ylabel = "Value", size = (382*2, 250),
     tickfont = font(14), guidefont = font(14), legendfont = font(14))
 plot!(x, label = "x", c = :black)
 plot!(y, label = "y", c = :red, ls = :dot)
@@ -109,7 +109,7 @@ plot!(ηs[ηs .> 0], pas_xy, marker = stroke(:black), c = :black, label = L"x \t
 plot!(ηs[ηs .> 0], pas_yx, marker = stroke(:red), c = :red, label = L"y \to x")
 hline!([0], ls = :dash, α = 0.6, label = "", c = :grey)
 
-pcomb = plot(p_te, p_pa, layout = (1, 2), size = (382, 200),
+pcomb = plot(p_te, p_pa, layout = (1, 2), size = (382*2, 300),
     tickfont = font(12), guidefont = font(12), legendfont = font(12))
 savefig(pcomb, "logistic2_te_and_pas.png"); # hide
 nothing # hide

diff --git a/docs/src/causalitytests/SMeasureTest.md b/docs/src/causalitytests/SMeasureTest.md
@@ -6,4 +6,4 @@ SMeasureTest
 
 # Tutorials
 
-- [`SMeasureTest` on scalar time series](@ref tutorial_smeasuretest).
+- [`SMeasureTest` on scalar time series](@ref tutorial_SMeasureMest).
diff --git a/docs/src/causalitytests/abstract_test_types.md b/docs/src/causalitytests/abstract_test_types.md
@@ -0,0 +1,22 @@
+
+# Abstract causality test types
+
+```@docs
+CausalityTest
+```
+
+# Distance based casuality tests
+
+```@docs
+DistanceBasedCausalityTest
+```
+
+## Entropy based causality tests
+
+```@docs
+EntropyBasedCausalityTest
+```
+
+```@docs
+TransferEntropyCausalityTest
+```
diff --git a/docs/src/causalitytests/an_introduction.md b/docs/src/causalitytests/an_introduction.md
@@ -0,0 +1,8 @@
+
+# An introduction to time series causality
+
+
+[1]:
+    Hannisdal, B., & Peters, S. E. (2011). Phanerozoic Earth system evolution and marine biodiversity. science, 334(6059), 1121-1124.
+[2]:
+    Dunhill, A. M., Hannisdal, B., & Benton, M. J. (2014). Disentangling rock record bias and common-cause from redundancy in the British fossil record. Nature communications, 5, 4818.
diff --git a/docs/src/causalitytests/causality_from_dynamical_systems.md b/docs/src/causalitytests/causality_from_dynamical_systems.md
@@ -1,7 +1,7 @@
 
-# [Causality in dynamical systems](@id causality_dynamical_systems)
+# [Testing for causality in dynamical systems](@id causality_dynamical_systems)
 
-## General syntax
+## Syntax
 
 The syntax for quantifying directional causality between variables of dynamical systems is 
 

diff --git a/docs/src/causalitytests/causality_from_time_series.md b/docs/src/causalitytests/causality_from_time_series.md
diff --git a/docs/src/causalitytests/causality_from_uncertain_data.md b/docs/src/causalitytests/causality_from_uncertain_data.md
@@ -1,14 +1,6 @@
+# [List of `causality` methods for uncertain data](@id causality_uncertaindata)
 
-# [Uncertainty handling](@id uncertainty_handling)
-
-All high-level causality test are integrated with the uncertainty handling machinery in 
-[UncertainData.jl](https://github.com/kahaaga/UncertainData.jl). Any combination of real-valued vectors, `Vector{<:AbstractUncertainValue}`, or `AbstractUncertainValueDataset` are accepted as inputs to `causality`, making uncertainty quantification on the causality statistics a breeze.
-
-For more fine grained control over the analysis, check out the [syntax overview](@ref syntax_overview) for low-level estimators.
-
-## List of `causality` methods for uncertain data
-
-If both indices and values have uncertainties, use one of the following methods:
+If your time series are uncertain both either in indices, values or both, then use one of the following strategies to compute causality statistics over the uncertain time series.
 
 - [Naive resampling](@ref causality_uncertain_naiveresampling)
 - [Naive constrained resampling](@ref causality_uncertain_naiveconstrained_resampling)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,4 +6,4 @@ SMeasureTest

		# Tutorials

		- [`SMeasureTest` on scalar time series](@ref tutorial_smeasuretest).
		- [`SMeasureTest` on scalar time series](@ref tutorial_SMeasureMest).