1use statrs::distribution::{ChiSquared as ChiSquaredDist, ContinuousCDF};
6
7use crate::dataset::Dataset;
8use crate::discrete::{
9 power_divergence_conditional, power_divergence_unconditional, DiscreteOutcome,
10};
11use crate::error::CIError;
12use crate::strategy::{CIResult, CITest, DataType, IndependenceRule, TestMeta};
13
14macro_rules! power_divergence_test {
16 ($(#[$doc:meta])* $test:ident, $name:literal, $lambda:expr) => {
17 $(#[$doc])*
18 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
19 pub struct $test {
20 pub yates: bool,
22 }
23
24 impl $test {
25 #[must_use]
27 pub fn new() -> Self {
28 Self { yates: true }
29 }
30 }
31
32 impl Default for $test {
33 fn default() -> Self {
34 Self::new()
35 }
36 }
37
38 impl CITest for $test {
39 fn test_impl(
40 &self,
41 data: &Dataset,
42 x: usize,
43 y: usize,
44 z: &[usize],
45 ) -> Result<CIResult, CIError> {
46 run_power_divergence(data, x, y, z, $lambda, self.yates)
47 }
48
49 fn meta(&self) -> TestMeta {
50 discrete_meta($name)
51 }
52 }
53 };
54}
55
56power_divergence_test! {
57 ChiSquared, "chi_squared", 1.0
63}
64
65power_divergence_test! {
66 LogLikelihood, "log_likelihood", 0.0
72}
73
74power_divergence_test! {
75 CressieRead, "cressie_read", 2.0 / 3.0
81}
82
83power_divergence_test! {
84 FreemanTukey, "freeman_tukey", -0.5
89}
90
91power_divergence_test! {
92 ModifiedLikelihood, "modified_likelihood", -1.0
100}
101
102#[allow(clippy::cast_precision_loss)]
111fn cramers_v(statistic: f64, n: usize, kx: usize, ky: usize) -> Option<f64> {
112 let k = kx.min(ky);
113 if k < 2 || n == 0 {
114 return None;
115 }
116 Some((statistic.max(0.0) / (n as f64 * (k as f64 - 1.0))).sqrt())
117}
118
119fn chi_squared_sf(statistic: f64, dof: usize) -> Result<f64, CIError> {
122 if dof == 0 {
123 return Ok(1.0);
124 }
125 if statistic.is_infinite() {
126 return Ok(0.0);
127 }
128 #[allow(clippy::cast_precision_loss)]
129 let p = ChiSquaredDist::new(dof as f64)
130 .map_err(|e| CIError::Numeric(format!("chi-squared distribution: {e}")))?
131 .sf(statistic);
132 Ok(p)
133}
134
135#[allow(
144 clippy::many_single_char_names,
145 reason = "x, y, z are the standard conditional-independence variable names from the contract"
146)]
147fn run_power_divergence(
148 data: &Dataset,
149 x: usize,
150 y: usize,
151 z: &[usize],
152 lambda: f64,
153 yates: bool,
154) -> Result<CIResult, CIError> {
155 let (x_codes, kx) = data.discrete(x)?;
156 let (y_codes, ky) = data.discrete(y)?;
157
158 let DiscreteOutcome { statistic, dof } = if z.is_empty() {
159 power_divergence_unconditional(x_codes, y_codes, kx, ky, lambda, yates)
160 } else {
161 let partition = data.strata_partition(z)?;
162 power_divergence_conditional(x_codes, y_codes, kx, ky, &partition, lambda, yates)
163 };
164
165 let p_value = chi_squared_sf(statistic, dof)?;
166 let effect_size = cramers_v(statistic, data.n_rows(), kx, ky);
167
168 Ok(CIResult {
169 statistic: Some(statistic),
170 p_value,
171 dof: Some(dof),
172 effect_size,
173 })
174}
175
176fn discrete_meta(name: &'static str) -> TestMeta {
180 TestMeta {
181 name,
182 data_types: &[DataType::Discrete],
183 symmetric: true,
184 rule: IndependenceRule::PValueGe,
185 }
186}
187
188#[cfg(test)]
189mod tests {
190 use super::*;
191 use crate::dataset::ColumnKind;
192
193 fn discrete_dataset(cols: Vec<(&str, Vec<f64>)>) -> Dataset {
194 Dataset::from_columns(
195 cols.into_iter()
196 .map(|(name, values)| (name.to_string(), ColumnKind::Discrete, values))
197 .collect(),
198 )
199 .unwrap()
200 }
201
202 fn assert_discrete_contract(test: &dyn CITest, expected_name: &str) {
203 let data = discrete_dataset(vec![
204 ("x", vec![1., 1., 2., 2., 1., 1., 2., 2.]),
205 ("y", vec![1., 2., 1., 2., 1., 2., 1., 2.]),
206 ]);
207 let result = test.test(&data, 0, 1, &[]).unwrap();
208 let Some(statistic) = result.statistic else {
209 panic!("{expected_name}: independent data must produce a statistic");
210 };
211 assert!(
212 statistic.abs() < 1e-9,
213 "{expected_name}: expected a near-zero statistic for independent data, got {statistic}"
214 );
215 assert_eq!(
216 result.dof,
217 Some(1),
218 "{expected_name}: expected one degree of freedom for independent data"
219 );
220 assert!(
221 result.p_value > 0.99,
222 "{expected_name}: expected a p-value above 0.99 for independent data, got {}",
223 result.p_value
224 );
225
226 let meta = test.meta();
227 assert_eq!(
228 meta.name, expected_name,
229 "{expected_name}: metadata must retain the family name"
230 );
231 assert_eq!(
232 meta.data_types,
233 &[DataType::Discrete],
234 "{expected_name}: metadata must accept discrete data"
235 );
236 assert!(
237 meta.symmetric,
238 "{expected_name}: metadata must declare a symmetric test"
239 );
240 assert_eq!(
241 meta.rule,
242 IndependenceRule::PValueGe,
243 "{expected_name}: metadata must use the p-value-greater-or-equal rule"
244 );
245 }
246
247 #[test]
248 fn family_members_share_contract() {
249 for (name, test) in [
250 (
251 "chi_squared",
252 &ChiSquared::new() as &dyn crate::strategy::CITest,
253 ),
254 ("log_likelihood", &LogLikelihood::new()),
255 ("cressie_read", &CressieRead::new()),
256 ("freeman_tukey", &FreemanTukey::new()),
257 ("modified_likelihood", &ModifiedLikelihood::new()),
258 ] {
259 assert_discrete_contract(test, name);
260 }
261 }
262
263 #[test]
264 fn contract_failures_identify_the_family() {
265 struct WrongResult;
266
267 impl CITest for WrongResult {
268 fn test_impl(
269 &self,
270 _data: &Dataset,
271 _x: usize,
272 _y: usize,
273 _z: &[usize],
274 ) -> Result<CIResult, CIError> {
275 Ok(CIResult {
276 statistic: Some(1.0),
277 p_value: 1.0,
278 dof: Some(1),
279 effect_size: None,
280 })
281 }
282
283 fn meta(&self) -> TestMeta {
284 super::discrete_meta("wrong_result")
285 }
286 }
287
288 let panic = std::panic::catch_unwind(|| {
289 assert_discrete_contract(&WrongResult, "wrong_result");
290 })
291 .expect_err("the intentionally invalid result must violate the contract");
292 let message = panic
293 .downcast_ref::<String>()
294 .map(String::as_str)
295 .or_else(|| panic.downcast_ref::<&str>().copied())
296 .expect("assertion panics include a message");
297 assert!(message.contains("wrong_result"), "{message}");
298 }
299
300 mod chi_squared {
301 use super::discrete_dataset as ds;
302 use super::*;
303 use crate::dataset::ColumnKind;
304
305 #[test]
306 fn unconditional_dependent_with_yates() {
307 let data = ds(vec![
309 ("x", vec![1., 1., 1., 1., 2., 2., 2., 2.]),
310 ("y", vec![1., 1., 1., 1., 2., 2., 2., 2.]),
311 ]);
312 let r = ChiSquared::new().test(&data, 0, 1, &[]).unwrap();
313 assert!(
314 (r.statistic.unwrap() - 4.5).abs() < 1e-9,
315 "got {:?}",
316 r.statistic
317 );
318 assert_eq!(r.dof, Some(1));
319 }
320
321 #[test]
322 fn yates_off_changes_statistic() {
323 let data = ds(vec![
325 ("x", vec![1., 1., 1., 1., 2., 2., 2., 2.]),
326 ("y", vec![1., 1., 1., 1., 2., 2., 2., 2.]),
327 ]);
328 let r = ChiSquared { yates: false }.test(&data, 0, 1, &[]).unwrap();
329 assert!(
330 (r.statistic.unwrap() - 8.0).abs() < 1e-9,
331 "got {:?}",
332 r.statistic
333 );
334 }
335
336 #[test]
337 fn conditional_independent() {
338 let data = ds(vec![
339 ("x", vec![1., 1., 2., 2., 1., 1., 2., 2.]),
340 ("y", vec![1., 2., 1., 2., 1., 2., 1., 2.]),
341 ("z", vec![1., 1., 1., 1., 2., 2., 2., 2.]),
342 ]);
343 let r = ChiSquared::new().test(&data, 0, 1, &[2]).unwrap();
344 assert!(r.statistic.unwrap().abs() < 1e-9);
345 assert_eq!(r.dof, Some(2));
346 assert!(r.p_value > 0.99);
347 }
348
349 #[test]
350 fn wrong_column_kind_errors() {
351 let data = Dataset::from_columns(vec![
352 ("x".into(), ColumnKind::Continuous, vec![1., 2., 3.]),
353 ("y".into(), ColumnKind::Discrete, vec![1., 2., 3.]),
354 ])
355 .unwrap();
356 assert!(matches!(
357 ChiSquared::new().test(&data, 0, 1, &[]),
358 Err(CIError::WrongColumnKind(_))
359 ));
360 }
361 }
362
363 mod log_likelihood {
364 use super::discrete_dataset as ds;
365 use super::*;
366
367 #[test]
368 fn dependent_table_pins_lambda_and_effect_size() {
369 let x = vec![
372 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
373 1., 1., 1., 1., 1., 1.,
374 ];
375 let y = vec![
376 0., 0., 0., 0., 0., 0., 1., 1., 2., 2., 2., 2., 0., 0., 0., 1., 1., 1., 1., 1., 1.,
377 1., 2., 2., 2., 2., 2.,
378 ];
379 let data = ds(vec![("x", x), ("y", y)]);
380 let r = LogLikelihood::new().test(&data, 0, 1, &[]).unwrap();
381 assert_eq!(r.dof, Some(2));
382 assert!((r.statistic.unwrap() - 3.738_650_145_2).abs() < 1e-6);
383 assert!((r.effect_size.unwrap() - 0.372_113_590_0).abs() < 1e-6);
384 }
385 }
386
387 mod cressie_read {
388 use super::discrete_dataset as ds;
389 use super::*;
390
391 #[test]
392 fn balanced_independent_table_has_finite_effect_size() {
393 let data = ds(vec![
398 (
399 "x",
400 vec![
401 0., 0., 0., 0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1., 1.,
402 ],
403 ),
404 (
405 "y",
406 vec![
407 0., 0., 0., 0., 1., 1., 1., 1., 0., 0., 0., 0., 1., 1., 1., 1.,
408 ],
409 ),
410 ]);
411 let r = CressieRead::new().test(&data, 0, 1, &[]).unwrap();
412 let effect = r.effect_size.expect("effect size should be present");
413 assert!(
414 effect.is_finite(),
415 "effect size must be finite, got {effect}"
416 );
417 assert!(
418 effect < 1e-9,
419 "balanced independent table -> ~0 effect, got {effect}"
420 );
421 }
422
423 #[test]
424 fn dependent_table_pins_lambda_and_effect_size() {
425 let x = vec![
428 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
429 1., 1., 1., 1., 1., 1.,
430 ];
431 let y = vec![
432 0., 0., 0., 0., 0., 0., 1., 1., 2., 2., 2., 2., 0., 0., 0., 1., 1., 1., 1., 1., 1.,
433 1., 2., 2., 2., 2., 2.,
434 ];
435 let data = ds(vec![("x", x), ("y", y)]);
436 let r = CressieRead::new().test(&data, 0, 1, &[]).unwrap();
437 assert_eq!(r.dof, Some(2));
438 assert!((r.statistic.unwrap() - 3.629_764_546_5).abs() < 1e-6);
439 assert!((r.effect_size.unwrap() - 0.366_654_774_9).abs() < 1e-6);
440 }
441 }
442
443 mod freeman_tukey {
444 use super::discrete_dataset as ds;
445 use super::*;
446
447 #[test]
448 fn dependent_table_pins_lambda_and_effect_size() {
449 let x = vec![
452 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
453 1., 1., 1., 1., 1., 1.,
454 ];
455 let y = vec![
456 0., 0., 0., 0., 0., 0., 1., 1., 2., 2., 2., 2., 0., 0., 0., 1., 1., 1., 1., 1., 1.,
457 1., 2., 2., 2., 2., 2.,
458 ];
459 let data = ds(vec![("x", x), ("y", y)]);
460 let r = FreemanTukey::new().test(&data, 0, 1, &[]).unwrap();
461 assert_eq!(r.dof, Some(2));
462 assert!((r.statistic.unwrap() - 3.868_242_083_0).abs() < 1e-6);
463 assert!((r.effect_size.unwrap() - 0.378_507_893_3).abs() < 1e-6);
464 }
465 }
466
467 mod modified_likelihood {
468 use super::discrete_dataset as ds;
469 use super::*;
470
471 #[test]
472 fn structural_zero_gives_p_zero() {
473 let data = ds(vec![
476 ("x", vec![0., 0., 0., 0., 1., 1., 1., 1., 2., 2., 2., 2.]),
477 ("y", vec![0., 0., 1., 1., 0., 0., 1., 1., 2., 2., 2., 2.]),
478 ]);
479 let r = ModifiedLikelihood::new().test(&data, 0, 1, &[]).unwrap();
480 assert!(r.statistic.unwrap().is_infinite());
481 assert!(r.p_value.total_cmp(&0.0).is_eq());
483 }
484 }
485}