Skip to main content

fastcit_core/ci_tests/
pearson_correlation.rs

1//! Pearson / partial-correlation conditional-independence test (continuous).
2
3use statrs::distribution::{ContinuousCDF, StudentsT};
4
5use crate::correlation::partial_correlation;
6use crate::dataset::Dataset;
7use crate::error::CIError;
8use crate::strategy::{CIResult, CITest, DataType, IndependenceRule, TestMeta};
9
10/// Pearson correlation test. With a non-empty conditioning set it computes the
11/// partial correlation by regressing X and Y on `[1, Z]` (intercept included)
12/// and correlating the residuals.
13#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
14pub struct PearsonCorrelation;
15
16impl PearsonCorrelation {
17    /// Construct the test (no configuration in this slice).
18    #[must_use]
19    pub fn new() -> Self {
20        Self
21    }
22}
23
24/// Two-tailed p-value for H₀: ρ = 0 from `r` and `dof` via the t-distribution.
25///
26/// # Errors
27///
28/// Returns [`CIError::DegenerateData`] if `|r| == 1` (t undefined) and
29/// [`CIError::Numeric`] if the t-distribution construction fails.
30fn correlation_p_value(r: f64, dof: usize) -> Result<f64, CIError> {
31    if (1.0 - r * r) <= 0.0 {
32        return Err(CIError::DegenerateData(
33            "correlation is ±1; t-statistic is undefined".to_string(),
34        ));
35    }
36    #[allow(clippy::cast_precision_loss)]
37    let dof_f = dof as f64;
38    let t = r * (dof_f / (1.0 - r * r)).sqrt();
39    let dist = StudentsT::new(0.0, 1.0, dof_f)
40        .map_err(|e| CIError::Numeric(format!("Student's t distribution: {e}")))?;
41    Ok(2.0 * dist.sf(t.abs()))
42}
43
44impl CITest for PearsonCorrelation {
45    fn test_impl(
46        &self,
47        data: &Dataset,
48        x: usize,
49        y: usize,
50        z: &[usize],
51    ) -> Result<CIResult, CIError> {
52        let (r, dof) = partial_correlation(data, x, y, z)?;
53        let p_value = correlation_p_value(r, dof)?;
54        Ok(CIResult {
55            statistic: Some(r),
56            p_value,
57            dof: Some(dof),
58            effect_size: Some(r.abs()),
59        })
60    }
61
62    fn meta(&self) -> TestMeta {
63        TestMeta {
64            name: "pearson_correlation",
65            data_types: &[DataType::Continuous],
66            symmetric: true,
67            rule: IndependenceRule::PValueGe,
68        }
69    }
70}
71
72#[cfg(test)]
73mod tests {
74    use super::*;
75    use crate::dataset::ColumnKind;
76
77    fn ds(cols: Vec<(&str, Vec<f64>)>) -> Dataset {
78        Dataset::from_columns(
79            cols.into_iter()
80                .map(|(n, v)| (n.to_string(), ColumnKind::Continuous, v))
81                .collect(),
82        )
83        .unwrap()
84    }
85
86    #[test]
87    fn unconditional_strong_correlation() {
88        // Strongly (but not perfectly) correlated, so 1 - r^2 > 0.
89        let data = ds(vec![
90            ("x", vec![1., 2., 3., 4., 5.]),
91            ("y", vec![2., 4.1, 5.9, 8.2, 9.8]),
92        ]);
93        let r = PearsonCorrelation::new().test(&data, 0, 1, &[]).unwrap();
94        assert!(r.statistic.unwrap() > 0.9);
95        assert_eq!(r.dof, Some(3));
96        assert!(r.p_value < 0.05);
97        assert!((r.effect_size.unwrap() - r.statistic.unwrap().abs()).abs() < 1e-12);
98    }
99
100    #[test]
101    fn perfect_correlation_is_degenerate() {
102        // r == 1 exactly -> t-statistic undefined; report a clear error.
103        let data = ds(vec![
104            ("x", vec![1., 2., 3., 4., 5.]),
105            ("y", vec![2., 4., 6., 8., 10.]),
106        ]);
107        assert!(matches!(
108            PearsonCorrelation::new().test(&data, 0, 1, &[]),
109            Err(CIError::DegenerateData(_))
110        ));
111    }
112
113    #[test]
114    fn constant_input_is_degenerate_not_panic() {
115        let data = ds(vec![
116            ("x", vec![1., 1., 1., 1., 1.]),
117            ("y", vec![2., 4., 6., 8., 10.]),
118        ]);
119        assert!(matches!(
120            PearsonCorrelation::new().test(&data, 0, 1, &[]),
121            Err(CIError::DegenerateData(_))
122        ));
123    }
124
125    #[test]
126    fn conditional_uses_intercept() {
127        // y = 2*z + 5, x = 3*z + 1: after regressing out [1, z] residuals are ~0.
128        let z = vec![1., 2., 3., 4., 5., 6., 7., 8.];
129        let x: Vec<f64> = z.iter().map(|v| 3.0 * v + 1.0).collect();
130        let y: Vec<f64> = z.iter().map(|v| 2.0 * v + 5.0).collect();
131        let data = ds(vec![("x", x), ("y", y), ("z", z)]);
132        // residuals are ~0 -> constant -> degenerate (exact collinear case).
133        let res = PearsonCorrelation::new().test(&data, 0, 1, &[2]);
134        assert!(matches!(res, Err(CIError::DegenerateData(_))));
135    }
136
137    #[test]
138    fn dof_accounts_for_conditioning_set() {
139        let z1 = vec![0.1, 0.9, 0.2, 0.8, 0.3, 0.7, 0.4, 0.6, 0.5, 1.1];
140        let z2 = vec![1.1, 0.2, 0.7, 0.3, 0.9, 0.4, 0.8, 0.1, 0.6, 0.5];
141        let x = vec![0.5, 0.4, 0.6, 0.2, 0.9, 0.1, 0.7, 0.3, 0.8, 0.2];
142        let y = vec![0.2, 0.7, 0.1, 0.8, 0.3, 0.9, 0.4, 0.6, 0.5, 0.7];
143        let data = ds(vec![("x", x), ("y", y), ("z1", z1), ("z2", z2)]);
144        let r = PearsonCorrelation::new()
145            .test(&data, 0, 1, &[2, 3])
146            .unwrap();
147        // n - |Z| - 2 = 10 - 2 - 2 = 6.
148        assert_eq!(r.dof, Some(6));
149    }
150
151    #[test]
152    fn wrong_kind_errors() {
153        let data = Dataset::from_columns(vec![
154            ("x".into(), ColumnKind::Discrete, vec![1., 2., 3.]),
155            ("y".into(), ColumnKind::Continuous, vec![1., 2., 3.]),
156        ])
157        .unwrap();
158        assert!(matches!(
159            PearsonCorrelation::new().test(&data, 0, 1, &[]),
160            Err(CIError::WrongColumnKind(_))
161        ));
162    }
163}