Skip to main content

fastcit_core/ci_tests/
fisher_z.rs

1//! Fisher-z conditional-independence test (continuous).
2
3use statrs::distribution::{ContinuousCDF, Normal};
4
5use crate::correlation::{clipped_fisher_transform, partial_correlation};
6use crate::dataset::Dataset;
7use crate::error::CIError;
8use crate::strategy::{CIResult, CITest, DataType, IndependenceRule, TestMeta};
9
10/// Fisher-z test on the (partial) correlation: `z = √(n − |Z| − 3) · atanh(ρ)`
11/// is approximately standard normal under `X ⊥ Y | Z`. The de-facto standard
12/// continuous CI test in causal discovery (pcalg's `gaussCItest`,
13/// causal-learn's `fisherz`, pgmpy's `FisherZ`).
14#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
15pub struct FisherZ;
16
17impl FisherZ {
18    /// Construct the test (no configuration).
19    #[must_use]
20    pub fn new() -> Self {
21        Self
22    }
23}
24
25impl CITest for FisherZ {
26    #[allow(
27        clippy::many_single_char_names,
28        reason = "x, y, z are the standard conditional-independence variable names from the contract"
29    )]
30    fn test_impl(
31        &self,
32        data: &Dataset,
33        x: usize,
34        y: usize,
35        z: &[usize],
36    ) -> Result<CIResult, CIError> {
37        let n = data.n_rows();
38        let n_z = z.len();
39
40        let (r, _dof) = partial_correlation(data, x, y, z)?;
41
42        // partial_correlation guarantees n >= |Z| + 3, so the radicand is >= 0
43        // (n == |Z| + 3 gives statistic 0 and p = 1, matching pgmpy).
44        #[allow(clippy::cast_precision_loss)]
45        let scale = ((n - n_z - 3) as f64).sqrt();
46        let statistic = scale * clipped_fisher_transform(r);
47
48        let normal =
49            Normal::new(0.0, 1.0).map_err(|e| CIError::Numeric(format!("standard normal: {e}")))?;
50        let p_value = 2.0 * normal.sf(statistic.abs());
51
52        Ok(CIResult {
53            statistic: Some(statistic),
54            p_value,
55            dof: None,
56            effect_size: Some(r.abs()),
57        })
58    }
59
60    fn meta(&self) -> TestMeta {
61        TestMeta {
62            name: "fisher_z",
63            data_types: &[DataType::Continuous],
64            symmetric: true,
65            rule: IndependenceRule::PValueGe,
66        }
67    }
68}
69
70#[cfg(test)]
71mod tests {
72    use super::*;
73    use crate::ci_tests::PearsonCorrelation;
74    use crate::dataset::ColumnKind;
75
76    fn ds(cols: Vec<(&str, Vec<f64>)>) -> Dataset {
77        Dataset::from_columns(
78            cols.into_iter()
79                .map(|(n, v)| (n.to_string(), ColumnKind::Continuous, v))
80                .collect(),
81        )
82        .unwrap()
83    }
84
85    #[test]
86    fn meta_is_correct() {
87        let m = FisherZ::new().meta();
88        assert_eq!(m.name, "fisher_z");
89        assert_eq!(m.data_types, &[DataType::Continuous]);
90        assert!(m.symmetric);
91        assert_eq!(m.rule, IndependenceRule::PValueGe);
92    }
93
94    #[test]
95    fn statistic_is_scaled_atanh_of_r() {
96        let data = ds(vec![
97            ("x", vec![0.2, 1.1, -0.4, 0.9, 1.8, -0.7, 0.3, 1.2]),
98            ("y", vec![1.0, 0.1, 0.8, -0.2, 0.4, 1.1, -0.3, 0.6]),
99        ]);
100        let fz = FisherZ::new().test(&data, 0, 1, &[]).unwrap();
101        let pc = PearsonCorrelation::new().test(&data, 0, 1, &[]).unwrap();
102        let r = pc.statistic.unwrap();
103        let expected = (8.0_f64 - 3.0).sqrt() * r.atanh();
104        assert!((fz.statistic.unwrap() - expected).abs() < 1e-12);
105        assert!(fz.dof.is_none());
106        assert!((fz.effect_size.unwrap() - r.abs()).abs() < 1e-12);
107        assert!(fz.p_value > 0.0 && fz.p_value <= 1.0);
108    }
109
110    #[test]
111    fn conditional_uses_n_minus_z_minus_3() {
112        let z: Vec<f64> = (0..20u8).map(|i| f64::from(i) * 0.37 % 1.9).collect();
113        let x: Vec<f64> = z
114            .iter()
115            .enumerate()
116            .map(|(i, v)| v + 0.31 * f64::from(u8::try_from(i).unwrap() % 5))
117            .collect();
118        let y: Vec<f64> = z
119            .iter()
120            .enumerate()
121            .map(|(i, v)| v - 0.27 * f64::from(u8::try_from(i).unwrap() % 7))
122            .collect();
123        let data = ds(vec![("x", x), ("y", y), ("z", z)]);
124        let fz = FisherZ::new().test(&data, 0, 1, &[2]).unwrap();
125        let pc = PearsonCorrelation::new().test(&data, 0, 1, &[2]).unwrap();
126        let r = pc.statistic.unwrap();
127        let expected = (20.0_f64 - 1.0 - 3.0).sqrt() * r.atanh();
128        assert!((fz.statistic.unwrap() - expected).abs() < 1e-12);
129    }
130
131    #[test]
132    fn perfect_correlation_is_clamped_finite() {
133        // y = 2x: r == 1 exactly. PearsonCorrelation errors here (t undefined);
134        // FisherZ instead clamps rho and reports a large finite statistic.
135        let x: Vec<f64> = (0..30u8).map(f64::from).collect();
136        let y: Vec<f64> = x.iter().map(|v| 2.0 * v).collect();
137        let data = ds(vec![("x", x), ("y", y)]);
138        let res = FisherZ::new().test(&data, 0, 1, &[]).unwrap();
139        let stat = res.statistic.unwrap();
140        assert!(stat.is_finite() && stat > 0.0);
141        assert!(res.p_value < 1e-12);
142        // effect_size reports the raw (unclipped) |r| — pgmpy convention.
143        assert!((res.effect_size.unwrap() - 1.0).abs() < 1e-12);
144    }
145
146    #[test]
147    fn is_independent_applies_p_value_ge_rule() {
148        let x: Vec<f64> = (0..24u8).map(|i| f64::from(i % 4)).collect();
149        let y: Vec<f64> = (0..24u8).map(|i| f64::from((i / 4) % 3)).collect();
150        let data = ds(vec![("x", x), ("y", y)]);
151        let fz = FisherZ::new();
152        let res = fz.test(&data, 0, 1, &[]).unwrap();
153        // The decision must equal the PValueGe rule applied to the p-value.
154        assert_eq!(
155            fz.is_independent(&data, 0, 1, &[], 0.05).unwrap(),
156            res.p_value >= 0.05
157        );
158    }
159}