xicor/
lib.rs

1//! This crate provides a reasonably efficient implementation of Sourav
2//! Chatterjee's xi-correlation coefficient, based on
3//! [the original paper](https://arxiv.org/pdf/1909.10140).
4//!
5//! Chatterjee's xi provides a measure of one variable's dependence on another
6//! in a much more general sense than, for example, Pearson's correlation
7//! coefficient. Suppose we have some sequence of random `x` values uniformly
8//! distributed from zero to tau. For each one, we compute `y = sin(x)`.
9//! Pearson's correlation coefficient will be roughly zero for this data, as it
10//! measures _linear_ dependence. On the other hand, Chatterjee's xi will be
11//! close to 1, representing that `y` is strongly a function of `x`, regardless
12//! of what function that may be.
13//!
14//! ## Highlights
15//!
16//! - Extremely simple to use (just call [`xicor()`], [`xicorf()`], etc, with
17//!   two slices containing the data)
18//! - Generic over `Ord`, as xi does not require calculations on the elements
19//!   themselves, only the ability to compare them. In principle even strings
20//!   could be correlated in this manner (lexicographically), for example.
21//! - Quite fast. In release mode on a 12-year-old machine (Dell M4700),
22//!   [`xicorf`] was able to process 1,000,000 pairs in 0.33 seconds. Profiling
23//!   revealed that 80% of this calculation lay in the standard library's
24//!   sorting routines.
25//!
26//! ## Progress
27//!
28//! - [x] Calculation of the xi coefficient itself
29//! - [ ] P-values for testing independence
30
31#[cfg(test)]
32mod tests;
33mod xicor;
34
35pub use xicor::*;