Skip to main content

fastcit_core/
registry.rs

1//! Registry of the built-in closed-form conditional-independence tests.
2//!
3//! A single source of truth listing the built-in tests that ship with this crate,
4//! so callers (and the language bindings) can enumerate the available tests and
5//! construct a default-configured one by its stable [`TestMeta::name`] without
6//! depending on every concrete struct.
7//!
8//! The default configuration for each test matches the scipy/pgmpy convention:
9//! the discrete power-divergence tests enable Yates' continuity correction, and
10//! [`PearsonEquivalence`] uses an equivalence margin of `0.1`.
11
12use crate::ci_tests::{
13    ChiSquared, CressieRead, FisherZ, FreemanTukey, Gcm, Hsic, Kci, LogLikelihood,
14    ModifiedLikelihood, PearsonCorrelation, PearsonEquivalence, Pillai,
15};
16use crate::strategy::{CITest, TestMeta};
17
18/// Default equivalence margin for [`PearsonEquivalence`] in [`make_default`].
19const DEFAULT_DELTA_THRESHOLD: f64 = 0.1;
20
21/// Construct every built-in test in its default configuration as a boxed
22/// [`CITest`]. The single source of truth that [`all_metas`] and
23/// [`make_default`] are derived from.
24fn default_tests() -> Vec<Box<dyn CITest>> {
25    vec![
26        Box::new(ChiSquared::new()),
27        Box::new(LogLikelihood::new()),
28        Box::new(CressieRead::new()),
29        Box::new(FreemanTukey::new()),
30        Box::new(ModifiedLikelihood::new()),
31        Box::new(PearsonCorrelation::new()),
32        Box::new(FisherZ::new()),
33        Box::new(PearsonEquivalence::new(DEFAULT_DELTA_THRESHOLD)),
34        Box::new(Hsic::new()),
35        Box::new(Kci::new()),
36        Box::new(Gcm::new()),
37        Box::new(Pillai::new()),
38    ]
39}
40
41/// Metadata for every built-in closed-form test, in registry order.
42#[must_use]
43pub fn all_metas() -> Vec<TestMeta> {
44    default_tests().iter().map(|t| t.meta()).collect()
45}
46
47/// Construct a default-configured boxed test by its [`TestMeta::name`].
48///
49/// Returns `None` if `name` does not match any built-in test. Default
50/// configuration: `chi_squared`/`log_likelihood`/`cressie_read`/
51/// `freeman_tukey`/`modified_likelihood` have Yates enabled, and
52/// `pearson_equivalence` uses `delta_threshold = 0.1`.
53#[must_use]
54pub fn make_default(name: &str) -> Option<Box<dyn CITest>> {
55    default_tests().into_iter().find(|t| t.meta().name == name)
56}
57
58#[cfg(test)]
59mod tests {
60    use super::*;
61    use std::collections::BTreeSet;
62
63    /// The stable names the registry must expose.
64    const EXPECTED_NAMES: [&str; 12] = [
65        "chi_squared",
66        "log_likelihood",
67        "cressie_read",
68        "freeman_tukey",
69        "modified_likelihood",
70        "pearson_correlation",
71        "fisher_z",
72        "pearson_equivalence",
73        "hsic",
74        "kci",
75        "gcm",
76        "pillai",
77    ];
78
79    #[test]
80    fn exposes_unique_metas() {
81        let metas = all_metas();
82        assert_eq!(
83            metas.len(),
84            EXPECTED_NAMES.len(),
85            "unexpected number of registered tests"
86        );
87        let names: BTreeSet<&str> = metas.iter().map(|m| m.name).collect();
88        assert_eq!(
89            names.len(),
90            EXPECTED_NAMES.len(),
91            "test names must be unique"
92        );
93        for expected in EXPECTED_NAMES {
94            assert!(names.contains(expected), "missing test `{expected}`");
95        }
96    }
97
98    #[test]
99    fn make_default_resolves_all_names() {
100        for name in EXPECTED_NAMES {
101            let test = make_default(name).unwrap_or_else(|| panic!("`{name}` did not resolve"));
102            assert_eq!(test.meta().name, name);
103        }
104    }
105
106    #[test]
107    fn make_default_unknown_is_none() {
108        assert!(make_default("not_a_real_test").is_none());
109    }
110}