Skip to main content

fastcit_core/ci_tests/
power_divergence.rs

1//! Named power-divergence tests, their configuration, and result conversion.
2//!
3//! All five tests use the contingency-table engine in [`crate::discrete`].
4
5use 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
14// Each named test differs only in its stable name and power-divergence λ.
15macro_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            /// Whether to apply Yates' continuity correction on 2×2 (sub-)tables.
21            pub yates: bool,
22        }
23
24        impl $test {
25            /// Construct the test with Yates' continuity correction enabled.
26            #[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    /// Pearson chi-squared test for discrete data (power divergence with λ = 1).
58    ///
59    /// When `yates` is set, Yates' continuity correction is applied on 2×2
60    /// (sub-)tables, matching `scipy.stats.chi2_contingency(correction=True)` and
61    /// pgmpy. Cramér's V is reported as the effect size.
62    ChiSquared, "chi_squared", 1.0
63}
64
65power_divergence_test! {
66    /// Log-likelihood ratio (G-test) for discrete data (power divergence with λ = 0).
67    ///
68    /// The per-cell statistic is `2 · Σ O·ln(O/E)`. When `yates` is set, Yates'
69    /// continuity correction is applied on 2×2 (sub-)tables. Cramér's V is reported
70    /// as the effect size.
71    LogLikelihood, "log_likelihood", 0.0
72}
73
74power_divergence_test! {
75    /// Cressie-Read power-divergence test for discrete data (λ = 2/3), the
76    /// recommended compromise between Pearson and the likelihood-ratio statistics.
77    ///
78    /// When `yates` is set, Yates' continuity correction is applied on 2×2
79    /// (sub-)tables. Cramér's V is reported as the effect size.
80    CressieRead, "cressie_read", 2.0 / 3.0
81}
82
83power_divergence_test! {
84    /// Freeman-Tukey power-divergence test for discrete data (λ = −1/2).
85    ///
86    /// When `yates` is set, Yates' continuity correction is applied on 2×2
87    /// (sub-)tables. Cramér's V is reported as the effect size.
88    FreemanTukey, "freeman_tukey", -0.5
89}
90
91power_divergence_test! {
92    /// Modified log-likelihood (Neyman) power-divergence test for discrete data
93    /// (λ = −1). The per-cell statistic is `2 · Σ E·ln(E/O)`; a structural zero
94    /// (`O = 0` with `E > 0`) drives the statistic to `+∞` and hence the p-value to
95    /// `0`.
96    ///
97    /// When `yates` is set, Yates' continuity correction is applied on 2×2
98    /// (sub-)tables. Cramér's V is reported as the effect size.
99    ModifiedLikelihood, "modified_likelihood", -1.0
100}
101
102/// Cramér's V = sqrt(stat / (n * (min(kx, ky) - 1))). Returns `None` when the
103/// smaller cardinality is < 2 (V undefined) or there are no rows.
104///
105/// The statistic is mathematically non-negative, but `powf` rounding in the
106/// power-divergence back-end can make it a tiny *negative* value on tables where
107/// observed == expected (e.g. a balanced independent table under Cressie-Read),
108/// which would turn the `sqrt` into `NaN`. Clamp the radicand at 0 so the effect
109/// size is a clean `0.0` there.
110#[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
119/// Survival function `P(χ²_dof > statistic)`, with the degenerate and infinite
120/// cases handled exactly: `dof == 0 ⇒ 1.0`, `statistic == +∞ ⇒ 0.0`.
121fn 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/// Run a power-divergence test with parameter `lambda` and Yates flag `yates`,
136/// returning the full [`CIResult`] (statistic, p-value via the chi-squared
137/// survival function, dof, Cramér's V effect size).
138///
139/// # Errors
140///
141/// Propagates [`CIError`] from reading the columns or constructing the
142/// chi-squared distribution.
143#[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
176/// Build the [`TestMeta`] common to every discrete power-divergence test: the
177/// given stable `name`, `[Discrete]`, symmetric, and the standard
178/// null-of-independence [`IndependenceRule::PValueGe`].
179fn 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            // [[4,0],[0,4]]: Yates makes stat = 4 * (1.5^2 / 2) = 4.5.
308            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            // Same [[4,0],[0,4]] without Yates -> full chi-square = 8.
324            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            // 2x3 dependent table (n=27, dof=2, Yates inert) pinning the log-likelihood
370            // lambda wiring and Cramér's V effect size against scipy references.
371            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            // Cressie-Read on a balanced independent 2x2 ([[4,4],[4,4]]): O == E, so
394            // the power-divergence statistic rounds to a tiny *negative* value. The
395            // Cramér's V effect size must still be a finite 0.0, not NaN (regression
396            // test for the cramers_v radicand clamp).
397            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            // 2x3 dependent table (n=27, dof=2, Yates inert) pinning the Cressie-Read
426            // lambda wiring and Cramér's V effect size against scipy references.
427            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            // 2x3 dependent table (n=27, dof=2, Yates inert) pinning the Freeman-Tukey
450            // lambda wiring and Cramér's V effect size against scipy references.
451            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            // A 3×3 table (dof != 1, so no Yates) with a structural zero in an
474            // active row/column -> statistic +∞ -> p = 0.
475            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            // p is exactly 0 for an infinite statistic.
482            assert!(r.p_value.total_cmp(&0.0).is_eq());
483        }
484    }
485}