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, PartialEq)]
14pub struct PearsonEquivalence {
15 pub delta_threshold: f64,
17}
18
19impl PearsonEquivalence {
20 #[must_use]
22 pub fn new(delta_threshold: f64) -> Self {
23 Self { delta_threshold }
24 }
25}
26
27impl CITest for PearsonEquivalence {
28 #[allow(
29 clippy::many_single_char_names,
30 reason = "x, y, z are the contract variable names; c is the Fisher-z scale factor"
31 )]
32 fn test_impl(
33 &self,
34 data: &Dataset,
35 x: usize,
36 y: usize,
37 z: &[usize],
38 ) -> Result<CIResult, CIError> {
39 if !(self.delta_threshold > 0.0 && self.delta_threshold < 1.0) {
40 return Err(CIError::DegenerateData(format!(
41 "delta_threshold must be in (0, 1), got {}",
42 self.delta_threshold
43 )));
44 }
45
46 let n = data.continuous(x)?.len();
47 let n_z = z.len();
48
49 let (rho_raw, _dof) = partial_correlation(data, x, y, z)?;
50 let z_rho = clipped_fisher_transform(rho_raw);
51 let z_delta = self.delta_threshold.atanh();
52
53 #[allow(clippy::cast_precision_loss)]
56 let c = ((n - n_z - 3) as f64).sqrt();
57
58 let normal =
59 Normal::new(0.0, 1.0).map_err(|e| CIError::Numeric(format!("standard normal: {e}")))?;
60
61 let p_lower = 1.0 - normal.cdf(c * (z_rho + z_delta));
62 let p_upper = normal.cdf(c * (z_rho - z_delta));
63 let p_value = p_lower.max(p_upper);
64
65 Ok(CIResult {
66 statistic: Some(z_rho),
67 p_value,
68 dof: None,
69 effect_size: Some(rho_raw.abs()),
72 })
73 }
74
75 fn meta(&self) -> TestMeta {
76 TestMeta {
77 name: "pearson_equivalence",
78 data_types: &[DataType::Continuous],
79 symmetric: true,
80 rule: IndependenceRule::PValueLt,
81 }
82 }
83}
84
85#[cfg(test)]
86mod tests {
87 use super::*;
88 use crate::dataset::ColumnKind;
89
90 fn ds(cols: Vec<(&str, Vec<f64>)>) -> Dataset {
91 Dataset::from_columns(
92 cols.into_iter()
93 .map(|(n, v)| (n.to_string(), ColumnKind::Continuous, v))
94 .collect(),
95 )
96 .unwrap()
97 }
98
99 #[test]
100 fn meta_uses_pvalue_lt() {
101 let m = PearsonEquivalence::new(0.1).meta();
102 assert_eq!(m.name, "pearson_equivalence");
103 assert_eq!(m.rule, IndependenceRule::PValueLt);
104 assert_eq!(m.data_types, &[DataType::Continuous]);
105 assert!(m.symmetric);
106 }
107
108 #[test]
109 fn reports_fisher_z_statistic_and_no_dof() {
110 let data = ds(vec![
111 ("x", vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]),
112 ("y", vec![2.0, 1.0, 4.0, 3.0, 6.0, 5.0]),
113 ]);
114 let r = PearsonEquivalence::new(0.1).test(&data, 0, 1, &[]).unwrap();
115 assert!(r.dof.is_none());
116 let rho = r.statistic.unwrap().tanh();
118 assert!((r.effect_size.unwrap() - rho.abs()).abs() < 1e-9);
119 }
120
121 #[test]
122 fn out_of_range_delta_errors() {
123 let data = ds(vec![
125 ("x", vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]),
126 ("y", vec![2.0, 1.0, 4.0, 3.0, 6.0, 5.0]),
127 ]);
128 assert!(matches!(
129 PearsonEquivalence::new(1.5).test(&data, 0, 1, &[]),
130 Err(CIError::DegenerateData(_))
131 ));
132 }
133
134 #[test]
135 fn near_zero_correlation_declares_independence() {
136 let mut x = Vec::new();
140 let mut y = Vec::new();
141 for i in 0..50 {
142 x.push(f64::from(i));
143 y.push(1.0);
144 x.push(f64::from(i));
145 y.push(-1.0);
146 }
147 let data = ds(vec![("x", x), ("y", y)]);
148 assert!(PearsonEquivalence::new(0.2)
149 .is_independent(&data, 0, 1, &[], 0.05)
150 .unwrap());
151 }
152
153 #[test]
154 fn strong_correlation_not_independent_under_small_delta() {
155 let data = ds(vec![
158 ("x", vec![1., 2., 3., 4., 5.]),
159 ("y", vec![2., 4.1, 5.9, 8.2, 9.8]),
160 ]);
161 assert!(!PearsonEquivalence::new(0.05)
162 .is_independent(&data, 0, 1, &[], 0.05)
163 .unwrap());
164 }
165
166 #[test]
167 fn too_few_rows_is_degenerate() {
168 let data = ds(vec![
170 ("x", vec![1.0, 2.0, 3.0]),
171 ("y", vec![3.0, 2.0, 1.0]),
172 ("z", vec![1.0, 2.0, 3.0]),
173 ]);
174 assert!(matches!(
175 PearsonEquivalence::new(0.1).test(&data, 0, 1, &[2]),
176 Err(CIError::DegenerateData(_))
177 ));
178 }
179}