Pearson equivalence 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.PearsonEquivalence(data, delta_threshold=0.1)

>>> 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 = 2000
>>> z = rng.standard_normal(n)
>>> x = z + rng.standard_normal(n)  # X and Y depend on Z only
>>> y = z + rng.standard_normal(n)
>>> data = fastcit.Dataset({
...     "X": ("continuous", x),
...     "Y": ("continuous", y),
...     "Z": ("continuous", z),
... })

>>> # A small p-value supports equivalence: |rho| < threshold,
>>> # so X and Y are independent given Z.
>>> test = fastcit.PearsonEquivalence(data, delta_threshold=0.1)
>>> result = test.run_test("X", "Y", ["Z"])
>>> result.statistic
-0.01914
>>> result.p_value
0.0001431
>>> print(result.dof)
None
>>> result.effect_size
0.01914

pearson_equivalence(data, delta_threshold = 0.1)

library(fastcit)

# Each language makes its own random data, so the values differ from the other tabs.
set.seed(0)
n <- 2000
z <- rnorm(n)
x <- z + rnorm(n) # X and Y depend on Z only
y <- z + rnorm(n)
df <- data.frame(X = x, Y = y, Z = z)

data <- dataset(df)
# A small p-value supports equivalence: |rho| < threshold,
# so X and Y are independent given Z.
test <- pearson_equivalence(data, delta_threshold = 0.1)
res <- run_test(test, "X", "Y", "Z")
print(res$statistic)
#> [1] 0.01544
print(res$p_value)
#> [1] 7.443e-05
print(res$dof)
#> NULL
print(res$effect_size)
#> [1] 0.01544

new PearsonEquivalence(data, { deltaThreshold: 0.1 })

const { Dataset, PearsonEquivalence } = 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 = 2000;
const z = draw(n, normal);
const x = z.map((v) => v + normal()); // X and Y depend on Z only
const y = z.map((v) => v + normal());

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

// A small p-value supports equivalence: |rho| < threshold, so X and Y are independent given Z.
const test = new PearsonEquivalence(data, { deltaThreshold: 0.1 });
const result = test.runTest("X", "Y", ["Z"]);
console.log(result.statistic);
// -0.01296
console.log(result.pValue);
// 0.00004734
console.log(result.dof);
// null
console.log(result.effectSize);
// 0.01296

fastcit_core::ci_tests::PearsonEquivalence::new(0.1)

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

use fastcit_core::ci_tests::PearsonEquivalence;
use fastcit_core::dataset::{ColumnKind, Dataset};
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..2000).map(|_| normal()).collect();
    let x: Vec<f64> = z.iter().map(|v| v + normal()).collect(); // X and Y depend on Z only
    let y: Vec<f64> = z.iter().map(|v| v + 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();
    // A small p-value supports equivalence: |rho| < threshold, so X and Y are independent given Z.
    let result = PearsonEquivalence::new(0.1).test(&data, x, y, &[z])?;
    println!("{:?}", result.statistic);
    // Some(-0.01296)
    println!("{:?}", result.p_value);
    // 4.734e-5
    println!("{:?}", result.dof);
    // None
    println!("{:?}", result.effect_size);
    // Some(0.01296)
    Ok(())
}

Method#

FastCIT regresses X and Y on \([1, Z]\) with ordinary least squares. \(r\) is the Pearson correlation of the two residual vectors. \(n\) is the number of rows, and \(|Z|\) is the number of columns in Z.

The test checks \(H_0: |\rho| \geq \delta\) against \(H_1: |\rho| < \delta\). \(\rho\) is the partial correlation in the population, and \(\delta\) is delta_threshold.

\[\begin{split}\begin{aligned} z_r &= \operatorname{atanh}\left(\operatorname{clip}\left(r, -1 + 10^{-6}, 1 - 10^{-6}\right)\right), \\ c &= \sqrt{n - |Z| - 3}, \\ p_{\mathrm{lower}} &= 1 - \Phi\left(c \, (z_r + \operatorname{atanh}(\delta))\right), \\ p_{\mathrm{upper}} &= \Phi\left(c \, (z_r - \operatorname{atanh}(\delta))\right), \\ p &= \max\left(p_{\mathrm{lower}}, p_{\mathrm{upper}}\right). \end{aligned}\end{split}\]

The statistic is \(z_r\). is_independent returns true when \(p\) is less than the significance level. This rule is the opposite of the rule of the other tests. The effect size is \(|r|\), before the clip.