Skip to main content

fastcit_core/ci_tests/
pearson_equivalence.rs

1//! Pearson equivalence (TOST) 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/// Two One-Sided Tests (TOST) equivalence test on the partial correlation,
11/// using Fisher's z-transform. A *low* p-value (below the significance level)
12/// declares independence, so the rule is [`IndependenceRule::PValueLt`].
13#[derive(Debug, Clone, Copy, PartialEq)]
14pub struct PearsonEquivalence {
15    /// Equivalence margin on the correlation scale (the "negligible" effect).
16    pub delta_threshold: f64,
17}
18
19impl PearsonEquivalence {
20    /// Construct the test with the given equivalence margin.
21    #[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        // partial_correlation guarantees n >= |Z| + 3, so the radicand is >= 0
54        // (matching FisherZ, which relies on the same invariant).
55        #[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 reports the observed (un-clipped) partial correlation,
70            // matching Fisher-Z; the clip only guards the atanh statistic above.
71            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        // statistic is atanh(rho); effect_size is |rho|.
117        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        // delta_threshold must lie in (0, 1); 1.5 is rejected before any compute.
124        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        // Exactly-zero correlation by construction: each x value pairs with +1
137        // and -1 in y, so the covariance is 0. With delta 0.2 and n = 100 the
138        // TOST p-value falls below 0.05, so PValueLt declares independence.
139        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        // A near-perfect correlation with a tiny equivalence margin: the TOST
156        // p-value is large, so PValueLt does not declare independence.
157        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        // n=3, |Z|=1 -> n - |Z| - 3 = -1 < 0.
169        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}