1use 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#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
15pub struct FisherZ;
16
17impl FisherZ {
18 #[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 #[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 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 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 assert_eq!(
155 fz.is_independent(&data, 0, 1, &[], 0.05).unwrap(),
156 res.p_value >= 0.05
157 );
158 }
159}