1use 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#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
14pub struct PearsonCorrelation;
15
16impl PearsonCorrelation {
17 #[must_use]
19 pub fn new() -> Self {
20 Self
21 }
22}
23
24fn 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 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 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 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 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 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}