KCI test#

Data types:

X, Y and Z must be continuous.

API:

All tests use the same API. See one API for all tests.

Usage#

fastcit.KCI(data, kernel=None, bandwidth="heuristic", epsilon=1e-3)

>>> import numpy as np
>>> import fastcit

>>> # Each language makes its own random data, so the values differ from the other tabs.
>>> rng = np.random.default_rng(0)
>>> n = 200
>>> z = rng.standard_normal(n)
>>> x = z**2 + 0.5 * rng.standard_normal(n)  # nonlinear in Z
>>> y = z**2 + 0.5 * rng.standard_normal(n)
>>> data = fastcit.Dataset({
...     "X": ("continuous", x),
...     "Y": ("continuous", y),
...     "Z": ("continuous", z),
... })

>>> test = fastcit.KCI(data, bandwidth="median")
>>> result = test.run_test("X", "Y", ["Z"])
>>> result.statistic
9.425
>>> result.p_value
0.6176
>>> print(result.dof)
None
>>> result.effect_size
0.01423

kci(data, kernel = NULL, bandwidth = "heuristic", epsilon = 1e-3)

library(fastcit)

# Each language makes its own random data, so the values differ from the other tabs.
set.seed(1)
n <- 200
z <- rnorm(n)
x <- z^2 + 0.5 * rnorm(n) # nonlinear in Z
y <- z^2 + 0.5 * rnorm(n)
df <- data.frame(X = x, Y = y, Z = z)

data <- dataset(df)
test <- kci(data, bandwidth = "median")
res <- run_test(test, "X", "Y", "Z")
print(res$statistic)
#> [1] 14.52
print(res$p_value)
#> [1] 0.4581
print(res$dof)
#> NULL
print(res$effect_size)
#> [1] 0.01943

new KCI(data, { bandwidth: "heuristic", epsilon: 0.001 })

const { Dataset, KCI } = require("fastcit");

// Each language makes its own random data, so the values differ from the other tabs.
// Seeded generator (Park-Miller), so every run gives the same data.
let seed = 12345;
const uniform = () => (seed = (seed * 16807) % 2147483647) / 2147483647;
const normal = () =>
  Math.sqrt(-2 * Math.log(uniform())) * Math.cos(2 * Math.PI * uniform());
const draw = (n, f) => Array.from({ length: n }, f);

const n = 200;
const z = draw(n, normal);
const x = z.map((v) => v * v + 0.5 * normal()); // nonlinear in Z
const y = z.map((v) => v * v + 0.5 * normal());

const data = new Dataset({
  X: { kind: "continuous", values: x },
  Y: { kind: "continuous", values: y },
  Z: { kind: "continuous", values: z },
});

const test = new KCI(data, { bandwidth: "median" });
const result = test.runTest("X", "Y", ["Z"]);
console.log(result.statistic);
// 11.49
console.log(result.pValue);
// 0.5197
console.log(result.dof);
// null
console.log(result.effectSize);
// 0.02031

fastcit_core::ci_tests::Kci { kernel: KernelChoice::Auto, bandwidth: Bandwidth::Heuristic, epsilon: 1e-3 }

use std::f64::consts::PI;

use fastcit_core::ci_tests::Kci;
use fastcit_core::dataset::{ColumnKind, Dataset};
use fastcit_core::kernel::Bandwidth;
use fastcit_core::strategy::CITest;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Each language makes its own random data, so the values differ from the other tabs.
    // Seeded generator (Park-Miller), so every run gives the same data.
    let mut seed = 12345.0_f64;
    let mut uniform = move || {
        seed = seed * 16807.0 % 2_147_483_647.0;
        seed / 2_147_483_647.0
    };
    let mut normal = || (-2.0 * uniform().ln()).sqrt() * (2.0 * PI * uniform()).cos();
    let z: Vec<f64> = (0..200).map(|_| normal()).collect();
    let x: Vec<f64> = z.iter().map(|v| v * v + 0.5 * normal()).collect(); // nonlinear in Z
    let y: Vec<f64> = z.iter().map(|v| v * v + 0.5 * normal()).collect();

    let data = Dataset::from_columns(vec![
        ("X".into(), ColumnKind::Continuous, x),
        ("Y".into(), ColumnKind::Continuous, y),
        ("Z".into(), ColumnKind::Continuous, z),
    ])?;
    let x = data.index_of("X").unwrap();
    let y = data.index_of("Y").unwrap();
    let z = data.index_of("Z").unwrap();
    let result = Kci {
        bandwidth: Bandwidth::Median,
        ..Kci::new()
    }
    .test(&data, x, y, &[z])?;
    println!("{:?}", result.statistic);
    // Some(11.49)
    println!("{:?}", result.p_value);
    // 0.5197
    println!("{:?}", result.dof);
    // None
    println!("{:?}", result.effect_size);
    // Some(0.02031)
    Ok(())
}

Method#

With an empty Z, KCI runs the HSIC test with the gamma null. Otherwise, FastCIT standardises X, Y and Z with the sample standard deviation, which divides by \(n - 1\). The kernel of X uses \(\ddot X = (X, Z/2)\). The kernel of Y uses Y, and the kernel of Z uses Z. The default kernel is the RBF kernel \(k(a, b) = \exp\left(-\lVert a - b \rVert^2 / (2 \ell^2)\right)\). With bandwidth = "heuristic", \(\ell = w \sqrt{|Z|}\) for all three kernels, where \(|Z|\) is the number of columns in Z. \(w\) is 1.2 for \(n < 200\), 0.7 for \(200 \leq n < 1200\) and 0.4 for \(n \geq 1200\). With "median", \(\ell\) is the median of the non-zero distances between pairs of rows, divided by \(\sqrt{2}\).

\(\tilde K = H K H\) is a centred kernel matrix, with \(H = I - \frac{1}{n} \mathbf{1} \mathbf{1}^\top\). \(\varepsilon\) is epsilon.

\[\begin{split}\begin{aligned} R_Z &= \varepsilon \left( \tilde K_Z + \varepsilon I \right)^{-1}, \\ \tilde K_{\ddot X \mid Z} &= R_Z \, \tilde K_{\ddot X} \, R_Z, \\ \tilde K_{Y \mid Z} &= R_Z \, \tilde K_Y \, R_Z, \\ T &= \operatorname{tr}\left( \tilde K_{\ddot X \mid Z} \, \tilde K_{Y \mid Z} \right). \end{aligned}\end{split}\]

\(V_X\) has the columns \(\sqrt{\lambda} \, u\) for the eigenpairs \((\lambda, u)\) of \(\tilde K_{\ddot X \mid Z}\) with \(\lambda > 10^{-5} \lambda_{\max}\). \(V_Y\) is the same for \(\tilde K_{Y \mid Z}\).

\[\begin{split}\begin{aligned} W &= \left( V_X V_X^\top \right) \circ \left( V_Y V_Y^\top \right), \\ \text{mean} &= \operatorname{tr} W, \\ \text{variance} &= 2 \operatorname{tr}\left( W^2 \right). \end{aligned}\end{split}\]

The p-value is the upper tail at \(T\) of a gamma distribution. Its shape is \(\text{mean}^2 / \text{variance}\) and its scale is \(\text{variance} / \text{mean}\). The effect size is \(T / \sqrt{\operatorname{tr}\left( \tilde K_{\ddot X \mid Z}^2 \right) \operatorname{tr}\left( \tilde K_{Y \mid Z}^2 \right)}\).