Chatterjee coefficient (#383)

* Chatterjee coefficient.

* Finalize Chatterjee correlation

* Fix examples

* Fix badges

* Add missing references in tables

* Add reference

* Remove unnecessary folder

* Reproducible tests

* Use .= syntax

Project.toml

@@ -2,7 +2,7 @@ name = "Associations"
 uuid = "614afb3a-e278-4863-8805-9959372b9ec2"
 authors = ["Kristian Agasøster Haaga <[email protected]>", "Tor Einar Møller <[email protected]>", "George Datseris <[email protected]>"]
 repo = "https://github.com/kahaaga/Associations.jl.git"
-version = "4.0.0"
+version = "4.1.0"
 
 [deps]
 Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"

README.md

@@ -2,8 +2,8 @@
 
 [![CI](https://github.com/juliadynamics/Associations.jl/workflows/CI/badge.svg)](https://github.com/JuliaDynamics/Associations.jl/actions)
 [![](https://img.shields.io/badge/docs-latest_tagged-blue.svg)](https://juliadynamics.github.io/Associations.jl/stable/)
-[![](https://img.shields.io/badge/docs-dev_(master)-blue.svg)](https://juliadynamics.github.io/Associations.jl/dev/)
-[![codecov](https://codecov.io/gh/JuliaDynamics/Associations.jl/branch/master/graph/badge.svg?token=0b71n6x6AP)](https://codecov.io/gh/JuliaDynamics/Associations.jl)
+[![](https://img.shields.io/badge/docs-dev_(main)-blue.svg)](https://juliadynamics.github.io/Associations.jl/dev/)
+[[![codecov](https://codecov.io/gh/JuliaDynamics/Associations.jl/branch/master/graph/badge.svg?token=0b71n6x6AP)](https://codecov.io/gh/JuliaDynamics/Associations.jl)](https://img.shields.io/codecov/c/github/juliadynamics/Associations.jl/main)
 [![DOI](https://zenodo.org/badge/135443027.svg)](https://zenodo.org/badge/latestdoi/135443027)
 
 Associations.jl is a package for quantifying associations, independence testing and causal inference.

changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+From version v4.0 onwards, this package has been renamed to to Associations.jl.
+
+# 4.1
+
+- New association measure: `ChatterjeeCorrelation`.
+
+# 4.0 (package rename)
+
+The package has been renamed from CausalityTools.jl to Associations.jl.
+
 ## 3.0 (new major release)
 
 This release contains several breaking changes. Any code from before v3.0 will need 

docs/refs.bib

@@ -1289,4 +1289,37 @@ @article{Arnhold1999
   pages={419--430},
   year={1999},
   publisher={Elsevier}
+}
+
+@article{Chatterjee2021,
+  title={A new coefficient of correlation},
+  author={Chatterjee, Sourav},
+  journal={Journal of the American Statistical Association},
+  volume={116},
+  number={536},
+  pages={2009--2022},
+  year={2021},
+  publisher={Taylor \& Francis}
+}
+
+@article{Shi2022,
+  title={On the power of Chatterjee’s rank correlation},
+  author={Shi, Hongjian and Drton, Mathias and Han, Fang},
+  journal={Biometrika},
+  volume={109},
+  number={2},
+  pages={317--333},
+  year={2022},
+  publisher={Oxford University Press}
+}
+
+@article{Dette2013,
+  title={A Copula-Based Non-parametric Measure of Regression Dependence},
+  author={Dette, Holger and Siburg, Karl F and Stoimenov, Pavel A},
+  journal={Scandinavian Journal of Statistics},
+  volume={40},
+  number={1},
+  pages={21--41},
+  year={2013},
+  publisher={Wiley Online Library}
 }

docs/src/associations.md

@@ -114,6 +114,7 @@ CorrelationMeasure
 PearsonCorrelation
 PartialCorrelation
 DistanceCorrelation
+ChatterjeeCorrelation
 ```
 
 ## [Cross-map measures](@id cross_map_api)

docs/src/examples/examples_associations.md

@@ -1697,4 +1697,32 @@ using Random; rng = Xoshiro(1234);
 x = rand(rng, 300); y = rand(rng, 300) .* sin.(x); z = rand(rng, 300) .* y;
 est = RMCD(r = 0.5)
 association(est, x, y), association(est, x, z), association(est, x, z, y)
-```
+```
+
+## [[`ChatterjeeCorrelation`](@ref)](@id example_ChatterjeeCorrelation)
+
+```@example example_ChatterjeeCorrelation
+using Associations
+using Random; rng = Xoshiro(1234);
+x = rand(rng, 120)
+y = rand(rng, 120) .* sin.(x)
+```
+
+By construction, there will almust surely be no ties in `x`, so we can use the 
+fast estimate by setting `handle_ties == false`. 
+
+```@example example_ChatterjeeCorrelation
+association(ChatterjeeCorrelation(handle_ties = false), x, y)
+```
+
+If we have data where we know there are ties in the data, then
+we should set `handle_ties == true`.
+
+```@example example_ChatterjeeCorrelation
+w = rand(rng, 1:10, 120) # there will be some ties
+z = rand(rng, 1:15, 120) .* sin.(w) # introduce some dependence
+association(ChatterjeeCorrelation(handle_ties = true), w, z)
+```
+
+
+

docs/src/examples/examples_independence.md

@@ -117,6 +117,26 @@ enough evidence in the data to suggest directional coupling.
 
 ## [[`SurrogateAssociationTest`](@ref)](@id examples_surrogatetest)
 
+### [Chatterjee correlation](@id example_SurrogateAssociationTest_ChatterjeeCorrelation)
+
+```@example example_SurrogateAssociationTest_ChatterjeeCorrelation
+using Associations
+using Random; rng = Xoshiro(1234)
+n = 1000
+x, y = rand(1:50, n), rand(1:50, n)
+test = SurrogateAssociationTest(ChatterjeeCorrelation(), nshuffles = 19)
+independence(test, x, y)
+```
+
+As expected, the test indicates that we can't reject independence. What happens if we introduce
+a third variable that depends on `y`?
+
+```@example example_SurrogateAssociationTest_ChatterjeeCorrelation
+z = rand(1:20, n) .* y
+independence(test, y, z)
+```
+
+The test clearly picks up on the functional dependence.
 
 ### [Distance correlation](@id example_SurrogateAssociationTest_DistanceCorrelation)