treecf 0.2.3__tar.gz → 0.3.0__tar.gz

{treecf-0.2.3 → treecf-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treecf
-Version: 0.2.3
+Version: 0.3.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -29,6 +29,7 @@ Requires-Dist: lightgbm>=4.3 ; extra == 'dev'
 Requires-Dist: catboost>=1.2 ; extra == 'dev'
 Requires-Dist: scikit-learn>=1.4 ; extra == 'dev'
 Requires-Dist: matplotlib>=3.8 ; extra == 'dev'
+Requires-Dist: probcal>=0.2 ; extra == 'dev'
 Requires-Dist: mkdocs>=1.6 ; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5 ; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.27 ; extra == 'docs'
@@ -37,6 +38,9 @@ Requires-Dist: mkdocs-jupyter>=0.24 ; extra == 'docs'
 Requires-Dist: ipykernel>=6.29 ; extra == 'docs'
 Requires-Dist: lightgbm>=4.3 ; extra == 'lightgbm'
 Requires-Dist: scikit-learn>=1.4 ; extra == 'sklearn'
+Requires-Dist: pytest>=8.0 ; extra == 'test'
+Requires-Dist: hypothesis>=6.100 ; extra == 'test'
+Requires-Dist: probcal>=0.2 ; extra == 'test'
 Requires-Dist: matplotlib>=3.8 ; extra == 'viz'
 Requires-Dist: xgboost>=2.0 ; extra == 'xgboost'
 Provides-Extra: all
@@ -45,6 +49,7 @@ Provides-Extra: dev
 Provides-Extra: docs
 Provides-Extra: lightgbm
 Provides-Extra: sklearn
+Provides-Extra: test
 Provides-Extra: viz
 Provides-Extra: xgboost
 License-File: LICENSE
@@ -61,6 +66,8 @@ Project-URL: Issues, https://github.com/wlazlod/treecf/issues
 
 # treecf
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22069503.svg)](https://doi.org/10.5281/zenodo.22069503)
+
 **Constrained, threshold-aware counterfactual explanations for tree ensembles.**
 
 `treecf` answers the question: *"what is the minimal, feasible change to this instance such
@@ -124,6 +131,12 @@ proved = exp.explain(x, target=t, backend="exact")      # proof="optimal", a cer
 boxed = exp.explain(x, target=t, region=True)            # res.region.describe() -> "utilization <= 0.4"
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the test layers, and the
+project's hard invariants; report security issues privately per
+[SECURITY.md](SECURITY.md).
+
 ## License
 
 MIT

{treecf-0.2.3 → treecf-0.3.0}/README.md

@@ -1,5 +1,7 @@
 # treecf
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22069503.svg)](https://doi.org/10.5281/zenodo.22069503)
+
 **Constrained, threshold-aware counterfactual explanations for tree ensembles.**
 
 `treecf` answers the question: *"what is the minimal, feasible change to this instance such
@@ -63,6 +65,12 @@ proved = exp.explain(x, target=t, backend="exact")      # proof="optimal", a cer
 boxed = exp.explain(x, target=t, region=True)            # res.region.describe() -> "utilization <= 0.4"
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the test layers, and the
+project's hard invariants; report security issues privately per
+[SECURITY.md](SECURITY.md).
+
 ## License
 
 MIT

{treecf-0.2.3 → treecf-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "treecf"
-version = "0.2.3"
+version = "0.3.0"
 description = "Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) — fast Rust genetic search, exact optimality proofs, certified infeasibility, and recourse regions."
 readme = "README.md"
 license = { text = "MIT" }
@@ -44,6 +44,11 @@ all = [
     "scikit-learn>=1.4",
     "matplotlib>=3.8",
 ]
+test = [
+    "pytest>=8.0",
+    "hypothesis>=6.100",
+    "probcal>=0.2",
+]
 dev = [
     "maturin>=1.7",
     "pytest>=8.0",
@@ -56,6 +61,7 @@ dev = [
     "catboost>=1.2",
     "scikit-learn>=1.4",
     "matplotlib>=3.8",
+    "probcal>=0.2",
 ]
 docs = [
     "mkdocs>=1.6",
@@ -115,10 +121,11 @@ ignore_missing_imports = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "-q --strict-markers -m 'not bench'"
+addopts = "-q --strict-markers -m 'not bench and not slow'"
 markers = [
     "bench: non-gating performance smoke benchmarks (run with -m bench)",
     "rust: cross-language tests requiring the dev Rust extension (maturin develop)",
+    "slow: docs snippet/structure harnesses (run with -m slow)",
 ]
 filterwarnings = [
     "error",

{treecf-0.2.3 → treecf-0.3.0}/rust/Cargo.lock

@@ -419,7 +419,7 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
 name = "treecf-core"
-version = "0.2.3"
+version = "0.3.0"
 dependencies = [
  "numpy",
  "pyo3",

{treecf-0.2.3 → treecf-0.3.0}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "treecf-core"
-version = "0.2.3"
+version = "0.3.0"
 edition = "2021"
 # f64::next_down (cells.rs) stabilized in 1.86; pyo3 0.29 needs 1.83
 rust-version = "1.86"

{treecf-0.2.3 → treecf-0.3.0}/rust/src/cells.rs

@@ -152,7 +152,9 @@ pub fn feature_cells_joint(ensembles: &[&Ensemble]) -> Vec<Vec<Cell>> {
     let mut pairs: Vec<Vec<(f64, bool)>> = vec![Vec::new(); n_features];
     for ens in ensembles {
         for i in 0..ens.feature.len() {
-            if ens.feature[i] >= 0 {
+            // set-membership splits carry no threshold; their features partition
+            // into category blocks instead of interval cells
+            if ens.feature[i] >= 0 && ens.node_set[i] < 0 {
                 pairs[ens.feature[i] as usize].push((ens.threshold[i], ens.is_lt[i]));
             }
         }
@@ -160,6 +162,78 @@ pub fn feature_cells_joint(ensembles: &[&Ensemble]) -> Vec<Vec<Cell>> {
     pairs.iter().map(|p| build_cells(p)).collect()
 }
 
+/// Category blocks per feature across ensembles — port of
+/// `treecf.aim.cells.category_blocks`. Indexed by feature; numeric features get
+/// an empty vec. Two codes share a block iff no split in any ensemble separates
+/// them: set-membership splits partition by membership, numeric splits on a
+/// categorical feature (an isolation forest trained on raw codes) partition by
+/// threshold side. Blocks are ordered by smallest member (codes scan
+/// ascending), members ascend, and a block's representative is its first entry.
+///
+/// Panics where Python raises `ValueError` (cardinality disagreement), matching
+/// the `feature_cells_joint` convention.
+pub fn category_blocks_joint(ensembles: &[&Ensemble]) -> Vec<Vec<Vec<u32>>> {
+    let n_features = ensembles[0].n_features;
+    let mut cardinality = vec![0u32; n_features];
+    for ens in ensembles {
+        for (j, slot) in cardinality.iter_mut().enumerate() {
+            let k = ens.cardinality[j];
+            if k > 0 {
+                if *slot == 0 {
+                    *slot = k;
+                } else {
+                    assert_eq!(
+                        *slot, k,
+                        "ensembles disagree on the cardinality of feature {j}"
+                    );
+                }
+            }
+        }
+    }
+    let mut out = Vec::with_capacity(n_features);
+    for (j, &card) in cardinality.iter().enumerate() {
+        let k = card as usize;
+        if k == 0 {
+            out.push(Vec::new());
+            continue;
+        }
+        let mut signatures: Vec<Vec<bool>> = vec![Vec::new(); k];
+        for ens in ensembles {
+            for i in 0..ens.feature.len() {
+                if ens.feature[i] != j as i32 {
+                    continue;
+                }
+                if ens.node_set[i] >= 0 {
+                    for (code, sig) in signatures.iter_mut().enumerate() {
+                        sig.push(ens.set_contains(ens.node_set[i], code as f64));
+                    }
+                } else if ens.is_lt[i] {
+                    for (code, sig) in signatures.iter_mut().enumerate() {
+                        sig.push((code as f64) < ens.threshold[i]);
+                    }
+                } else {
+                    for (code, sig) in signatures.iter_mut().enumerate() {
+                        sig.push((code as f64) <= ens.threshold[i]);
+                    }
+                }
+            }
+        }
+        let mut blocks: Vec<Vec<u32>> = Vec::new();
+        let mut seen: Vec<usize> = Vec::new(); // block index -> a code carrying its signature
+        for code in 0..k {
+            match seen.iter().position(|&c| signatures[c] == signatures[code]) {
+                Some(b) => blocks[b].push(code as u32),
+                None => {
+                    seen.push(code);
+                    blocks.push(vec![code as u32]);
+                }
+            }
+        }
+        out.push(blocks);
+    }
+    out
+}
+
 /// Index of the unique cell containing `x` — port of `treecf.aim.cells.cell_index`.
 ///
 /// Panics where Python raises `ValueError`. The cells partition the whole line,
@@ -175,6 +249,7 @@ pub fn cell_index(cells: &[Cell], x: f64) -> usize {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::ir::Link;
 
     #[test]
     fn lt_le_collision_yields_singleton() {
@@ -252,4 +327,107 @@ mod tests {
         assert_eq!(cell_index(&cells, 1.0), 1);
         assert_eq!(cell_index(&cells, 1.5), 2);
     }
+
+    /// One set stump per word list, all on feature 0, cardinality `k`.
+    fn set_ens(sets: &[u64], k: u32) -> Ensemble {
+        let n = sets.len().max(1);
+        let mut feature = Vec::new();
+        let mut node_set = Vec::new();
+        let mut left = Vec::new();
+        let mut right = Vec::new();
+        let mut value = Vec::new();
+        let mut roots = Vec::new();
+        for (t, _) in sets.iter().enumerate() {
+            let base = (t * 3) as u32;
+            roots.push(base);
+            feature.extend_from_slice(&[0, -1, -1]);
+            node_set.extend_from_slice(&[t as i32, -1, -1]);
+            left.extend_from_slice(&[base + 1, 0, 0]);
+            right.extend_from_slice(&[base + 2, 0, 0]);
+            value.extend_from_slice(&[0.0, -1.0, 1.0]);
+        }
+        if sets.is_empty() {
+            roots.push(0);
+            feature.push(-1);
+            node_set.push(-1);
+            left.push(0);
+            right.push(0);
+            value.push(0.0);
+        }
+        let n_nodes = feature.len();
+        Ensemble::new(
+            feature,
+            vec![0.0; n_nodes],
+            vec![false; n_nodes],
+            vec![false; n_nodes],
+            left,
+            right,
+            value,
+            roots,
+            0.0,
+            Link::Identity,
+            n,
+        )
+        .unwrap()
+        .with_categories(
+            node_set,
+            (0..=sets.len() as u32).collect(),
+            sets.to_vec(),
+            {
+                let mut c = vec![0; n];
+                c[0] = k;
+                c
+            },
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn no_splits_one_block() {
+        let e = set_ens(&[], 4);
+        assert_eq!(e.category_blocks()[0], vec![vec![0, 1, 2, 3]]);
+    }
+
+    #[test]
+    fn one_set_two_blocks_numbered_by_smallest_member() {
+        let e = set_ens(&[0b101], 4); // {0, 2}
+        assert_eq!(e.category_blocks()[0], vec![vec![0, 2], vec![1, 3]]);
+    }
+
+    #[test]
+    fn two_sets_refine_to_singletons() {
+        let e = set_ens(&[0b101, 0b1100], 4); // {0,2} then {2,3}
+        assert_eq!(
+            e.category_blocks()[0],
+            vec![vec![0], vec![1], vec![2], vec![3]]
+        );
+    }
+
+    #[test]
+    fn joint_blocks_refine_and_numeric_splits_partition_codes() {
+        let a = set_ens(&[0b101], 4);
+        // a numeric stump on the same feature at 1.5 (an isolation forest would)
+        let b = {
+            let mut e = Ensemble::new(
+                vec![0, -1, -1],
+                vec![1.5, 0.0, 0.0],
+                vec![false, false, false],
+                vec![false, false, false],
+                vec![1, 0, 0],
+                vec![2, 0, 0],
+                vec![0.0, -1.0, 1.0],
+                vec![0],
+                0.0,
+                Link::Identity,
+                1,
+            )
+            .unwrap();
+            e = e
+                .with_categories(vec![-1, -1, -1], vec![0], vec![], vec![4])
+                .unwrap();
+            e
+        };
+        let joint = category_blocks_joint(&[&a, &b]);
+        assert_eq!(joint[0], vec![vec![0], vec![1], vec![2], vec![3]]);
+    }
 }

{treecf-0.2.3 → treecf-0.3.0}/rust/src/constraints.rs

@@ -35,6 +35,27 @@ pub struct Constraints {
     pub implications: Vec<(u32, f64, u32, f64)>, // cond_idx, cond_val, cons_idx, cons_val
     pub onehot: Vec<Vec<u32>>,
     pub allow_missing: Vec<(u32, f64, f64)>, // (feature, delta_to, delta_from), index-sorted
+    // (feature, allowed-code bitset words), index-sorted; an empty word list
+    // means the declared set is empty (nothing is allowed on that feature)
+    pub allowed_categories: Vec<(u32, Vec<u64>)>,
+}
+
+/// Membership of `v` in an allowed-code bitset: an integral code whose bit is
+/// set. Non-integral values are never members; codes beyond the words are not.
+#[inline]
+pub(crate) fn code_allowed(words: &[u64], v: f64) -> bool {
+    if !v.is_finite() {
+        return false;
+    }
+    let code = v as i64;
+    if code as f64 != v || code < 0 {
+        return false;
+    }
+    let word = (code >> 6) as usize;
+    if word >= words.len() {
+        return false;
+    }
+    (words[word] >> (code & 63)) & 1 == 1
 }
 
 /// Python `max(a, b)`: returns b only if b > a. Two consequences both mirrors
@@ -184,6 +205,12 @@ impl Constraints {
                 return false; // NaN sum compares false -> infeasible, like numpy
             }
         }
+        for (j, words) in &self.allowed_categories {
+            let v = row[*j as usize];
+            if !v.is_nan() && !code_allowed(words, v) {
+                return false;
+            }
+        }
         true
     }
 
@@ -239,6 +266,19 @@ impl Constraints {
                 row[j] = v;
             }
         }
+        for (j, words) in &self.allowed_categories {
+            let j = *j as usize;
+            // keep an allowed code; else the smallest allowed code (deterministic)
+            if words.is_empty() {
+                continue; // nothing legal to write; check rejects
+            }
+            if !row[j].is_nan() && !code_allowed(words, row[j]) {
+                if let Some(word) = words.iter().position(|&w| w != 0) {
+                    let bit = words[word].trailing_zeros() as usize;
+                    row[j] = (word * 64 + bit) as f64;
+                }
+            }
+        }
         // cyclic projection: boxes intersected with halfspaces, a few sweeps
         // (must mirror repair_matrix float-for-float: same term order, one
         // residual/denom division, lower-bound-first clipping)
@@ -345,6 +385,7 @@ mod tests {
             implications: vec![],
             onehot: vec![],
             allow_missing: vec![],
+            allowed_categories: vec![],
         }
     }