HSIC test#

Data types:

X and Y must be continuous. HSIC has no Z.

API:

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

Usage#

fastcit.HSIC(data, kernel=None, bandwidth="heuristic", null_dist="gamma", n_permutations=100, seed=0)

>>> 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 = 300
>>> x = rng.standard_normal(n)
>>> y = x**2 + 0.5 * rng.standard_normal(n)  # nonlinear dependence, zero correlation
>>> data = fastcit.Dataset({"X": ("continuous", x), "Y": ("continuous", y)})

>>> test = fastcit.HSIC(data, bandwidth="median")
>>> result = test.run_test("X", "Y")
>>> result.statistic
2629.3
>>> result.p_value
1.716e-42
>>> print(result.dof)
None
>>> result.effect_size
0.3072

hsic(data, kernel = NULL, bandwidth = "heuristic", null_dist = "gamma", n_permutations = 100L, seed = 0)

library(fastcit)

# Each language makes its own random data, so the values differ from the other tabs.
set.seed(0)
n <- 300
x <- rnorm(n)
y <- x^2 + 0.5 * rnorm(n) # nonlinear dependence, zero correlation
df <- data.frame(X = x, Y = y)

data <- dataset(df)
test <- hsic(data, bandwidth = "median")
res <- run_test(test, "X", "Y")
print(res$statistic)
#> [1] 2668.9
print(res$p_value)
#> [1] 1.728e-40
print(res$dof)
#> NULL
print(res$effect_size)
#> [1] 0.3140

new HSIC(data, { bandwidth: "heuristic", nullDist: "gamma", nPermutations: 100, seed: 0 })

const { Dataset, HSIC } = 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 = 300;
const x = draw(n, normal);
const y = x.map((v) => v * v + 0.5 * normal()); // nonlinear, zero correlation

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

const test = new HSIC(data, { bandwidth: "median" });
const result = test.runTest("X", "Y", []);
console.log(result.statistic);
// 2488.9
console.log(result.pValue);
// 1.902e-38
console.log(result.dof);
// null
console.log(result.effectSize);
// 0.3257

fastcit_core::ci_tests::Hsic { kernel: KernelChoice::Auto, bandwidth: Bandwidth::Heuristic, null_dist: NullDistribution::Gamma }

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

use fastcit_core::ci_tests::Hsic;
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 x: Vec<f64> = (0..300).map(|_| normal()).collect();
    // Nonlinear dependence with zero correlation.
    let y: Vec<f64> = x.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),
    ])?;
    let x = data.index_of("X").unwrap();
    let y = data.index_of("Y").unwrap();
    let result = Hsic {
        bandwidth: Bandwidth::Median,
        ..Hsic::new()
    }
    .test(&data, x, y, &[])?;
    println!("{:?}", result.statistic);
    // Some(2488.9)
    println!("{:?}", result.p_value);
    // 1.902e-38
    println!("{:?}", result.dof);
    // None
    println!("{:?}", result.effect_size);
    // Some(0.3257)
    Ok(())
}

Method#

FastCIT standardises X and Y with the sample standard deviation, which divides by \(n - 1\). \(K\) and \(L\) are the \(n \times n\) kernel matrices of X and Y. The default kernel is the RBF kernel, with length scale \(\ell\).

\[\begin{split}\begin{aligned} k_{\mathrm{RBF}}(a, b) &= \exp\left(-\frac{(a - b)^2}{2 \ell^2}\right), \\ k_{\mathrm{linear}}(a, b) &= a \, b. \end{aligned}\end{split}\]

With bandwidth = "heuristic", \(\ell\) is 0.8 for \(n < 200\), 0.5 for \(200 \leq n < 1200\) and 0.3 for \(n \geq 1200\). With "median", \(\ell\) is the median of the non-zero distances between pairs of rows, divided by \(\sqrt{2}\). \(H = I - \frac{1}{n} \mathbf{1} \mathbf{1}^\top\) is the centring matrix, \(\tilde K = H K H\) and \(\tilde L = H L H\).

\[T = \sum_{i,j} \tilde K_{ij} \, \tilde L_{ij} = \operatorname{tr}\left(\tilde K \tilde L\right).\]

With null_dist = "gamma", \(\mu_K\) is the mean of \(K_{ij}\) for \(i \neq j\), and \(\mu_L\) is the same for \(L\).

\[\begin{split}\begin{aligned} \mathbb{E} &= \frac{1}{n} \left( \frac{\operatorname{tr} K}{n} - \mu_K \right) \left( \frac{\operatorname{tr} L}{n} - \mu_L \right), \\ \mathbb{V} &= \frac{72 \, (n - 4)(n - 5)}{n (n - 1)(n - 2)(n - 3)} \, S, \\ S &= \frac{1}{n (n - 1)} \sum_{i \neq j} \left( \frac{\tilde K_{ij} \, \tilde L_{ij}}{6} \right)^2. \end{aligned}\end{split}\]

The p-value is the upper tail at \(T / n\) of a gamma distribution. Its shape is \(\mathbb{E}^2 / \mathbb{V}\) and its scale is \(n \, \mathbb{V} / \mathbb{E}\). With null_dist = "permutation", \(B\) random permutations \(\pi_b\) of the rows give

\[\begin{split}\begin{aligned} T_b &= \sum_{i,j} \tilde K_{ij} \, \tilde L_{\pi_b(i) \pi_b(j)}, \\ p &= \frac{1 + \#\{b : T_b \geq T\}}{1 + B}. \end{aligned}\end{split}\]

\(B\) is n_permutations. The effect size is \(T / \sqrt{\operatorname{tr}\left(\tilde K \tilde K\right) \operatorname{tr}\left(\tilde L \tilde L\right)}\).