pyruleanalyzer 2.1.0__tar.gz → 2.1.2__tar.gz

{pyruleanalyzer-2.1.0/pyruleanalyzer.egg-info → pyruleanalyzer-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyruleanalyzer
-Version: 2.1.0
+Version: 2.1.2
 Summary: Extract, refine and formally verify the rules of scikit-learn decision trees, random forests and gradient boosting, and export them as standalone Python, C and Arduino classifiers
 Author: GrupoCybersegurancaVirtus
 License-Expression: MIT
@@ -281,15 +281,15 @@ works for all three model types.
 | **Usage count** | Runs the refinement samples through the rules and counts how often each fires. | unchanged |
 | **Boundary merge** | Sibling leaves with the same output and complementary conditions (`<= T` and `> T`) are merged into their parent, repeatedly, until no pair is left. The merged rule carries the sum of the two usage counts. | unchanged |
 | **Low-usage removal** | Rules used `remove_below_n_classifications` times or fewer are removed, deepest first; the sibling of a removed rule is promoted. `-1` disables it, `0` removes only never-used rules. | may change |
-| **Inter-tree fusion** (GBDT, `refine_between_trees=True`) | Stages of one class with an identical region are folded into one rule whose contribution is the sum. The other stages abstain there. | unchanged |
+| **Inter-tree fusion** (GBDT, on by default; `refine_between_trees=False` turns it off) | Stages of one class with an identical region are folded into one rule whose contribution is the sum. The other stages abstain there. | unchanged |
 
 ```python
 # Random Forest: low-usage removal only (see below for why not inter-tree).
 model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1)
 
-# Gradient Boosting: also fold identical stages.
-model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1,
-                              refine_between_trees=True)
+# Gradient Boosting: identical stages are also folded (refine_between_trees,
+# on by default for GBDT).
+model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1)
 ```
 
 Merging siblings is a promotion upwards:
@@ -834,7 +834,7 @@ added condition) refuse NaN as before.
 | `.fit(X, y)` | Train the scikit-learn model and extract its rules |
 | `PyRuleAnalyzer.from_sklearn(model, feature_names=None, class_names=None)` | Wrap an already-fitted `DecisionTreeClassifier`, `RandomForestClassifier`, `ExtraTreesClassifier` (wrapped as a Random Forest; `get_params()["estimator"]` remembers the class, so refitting, also after `clone`, trains an `ExtraTreesClassifier` again) or `GradientBoostingClassifier` |
 | `PyRuleAnalyzer.create(train_path, test_path, model, params, refine)` | Same, from CSV files |
-| `.execute_rule_refinement(X, y, remove_below_n_classifications=-1, refine_between_trees=False, ...)` | Refine; returns `rules_before`, `rules_after`, `rules_removed`, `reduction_percent` |
+| `.execute_rule_refinement(X, y, remove_below_n_classifications=-1, refine_between_trees=None, ...)` | Refine; returns `rules_before`, `rules_after`, `rules_removed`, `reduction_percent` |
 | `.compare_initial_final_results(X, y)` | Metrics and disagreements, initial against refined |
 | `.predict(X, use_refined=True)`, `.predict_proba(X, ...)` | Vectorised prediction |
 | `.summary_report()` | A dict: model type, total rules, classes and every rule |
@@ -960,7 +960,7 @@ cd docs && make html
 
 ## Status
 
-Version 2.1.0; [CHANGELOG.md](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/CHANGELOG.md)
+Version 2.1.2; [CHANGELOG.md](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/CHANGELOG.md)
 says what changed. The figures on this page are drawn from real runs by
 [`docs/figures/make_figures.py`](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/docs/figures/make_figures.py).
 

{pyruleanalyzer-2.1.0 → pyruleanalyzer-2.1.2}/README.md

@@ -239,15 +239,15 @@ works for all three model types.
 | **Usage count** | Runs the refinement samples through the rules and counts how often each fires. | unchanged |
 | **Boundary merge** | Sibling leaves with the same output and complementary conditions (`<= T` and `> T`) are merged into their parent, repeatedly, until no pair is left. The merged rule carries the sum of the two usage counts. | unchanged |
 | **Low-usage removal** | Rules used `remove_below_n_classifications` times or fewer are removed, deepest first; the sibling of a removed rule is promoted. `-1` disables it, `0` removes only never-used rules. | may change |
-| **Inter-tree fusion** (GBDT, `refine_between_trees=True`) | Stages of one class with an identical region are folded into one rule whose contribution is the sum. The other stages abstain there. | unchanged |
+| **Inter-tree fusion** (GBDT, on by default; `refine_between_trees=False` turns it off) | Stages of one class with an identical region are folded into one rule whose contribution is the sum. The other stages abstain there. | unchanged |
 
 ```python
 # Random Forest: low-usage removal only (see below for why not inter-tree).
 model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1)
 
-# Gradient Boosting: also fold identical stages.
-model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1,
-                              refine_between_trees=True)
+# Gradient Boosting: identical stages are also folded (refine_between_trees,
+# on by default for GBDT).
+model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1)
 ```
 
 Merging siblings is a promotion upwards:
@@ -792,7 +792,7 @@ added condition) refuse NaN as before.
 | `.fit(X, y)` | Train the scikit-learn model and extract its rules |
 | `PyRuleAnalyzer.from_sklearn(model, feature_names=None, class_names=None)` | Wrap an already-fitted `DecisionTreeClassifier`, `RandomForestClassifier`, `ExtraTreesClassifier` (wrapped as a Random Forest; `get_params()["estimator"]` remembers the class, so refitting, also after `clone`, trains an `ExtraTreesClassifier` again) or `GradientBoostingClassifier` |
 | `PyRuleAnalyzer.create(train_path, test_path, model, params, refine)` | Same, from CSV files |
-| `.execute_rule_refinement(X, y, remove_below_n_classifications=-1, refine_between_trees=False, ...)` | Refine; returns `rules_before`, `rules_after`, `rules_removed`, `reduction_percent` |
+| `.execute_rule_refinement(X, y, remove_below_n_classifications=-1, refine_between_trees=None, ...)` | Refine; returns `rules_before`, `rules_after`, `rules_removed`, `reduction_percent` |
 | `.compare_initial_final_results(X, y)` | Metrics and disagreements, initial against refined |
 | `.predict(X, use_refined=True)`, `.predict_proba(X, ...)` | Vectorised prediction |
 | `.summary_report()` | A dict: model type, total rules, classes and every rule |
@@ -918,7 +918,7 @@ cd docs && make html
 
 ## Status
 
-Version 2.1.0; [CHANGELOG.md](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/CHANGELOG.md)
+Version 2.1.2; [CHANGELOG.md](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/CHANGELOG.md)
 says what changed. The figures on this page are drawn from real runs by
 [`docs/figures/make_figures.py`](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/docs/figures/make_figures.py).
 

{pyruleanalyzer-2.1.0 → pyruleanalyzer-2.1.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyruleanalyzer"
-version = "2.1.0"
+version = "2.1.2"
 description = "Extract, refine and formally verify the rules of scikit-learn decision trees, random forests and gradient boosting, and export them as standalone Python, C and Arduino classifiers"
 authors = [{ name = "GrupoCybersegurancaVirtus" }]
 readme = "README.md"

{pyruleanalyzer-2.1.0 → pyruleanalyzer-2.1.2}/pyruleanalyzer/cpn_mutants.py

@@ -227,10 +227,14 @@ def _double_output(doc: CPNDocument, info) -> bool:
 
 # Function to deposit a label outside the domain (A6).
 def _bad_label(doc: CPNDocument, info) -> bool:
+    # One past the largest class the correct net can predict; a fixed label
+    # such as 7 is a valid class of any model with eight or more classes.
+    known = list(info.get("labels") or []) + list(info.get("prediction") or [])
+    bad = max(known) + 1 if info.get("labels") else max(known + [0]) + 1_000_000
     page, name = info["producer_page"], info["producer"]
     for arc in doc.arcs(page, name, "TtoP"):
         if doc.place_of(page, arc) == "Prediction":
-            doc.set_inscription(arc, "7")
+            doc.set_inscription(arc, str(bad))
     return True
 
 
@@ -373,7 +377,7 @@ TREE_MUTANTS: List[Mutant] = [
            "dormant leaf always enabled, produces nothing", _dead_branch),
     Mutant("double_output", ("A5", "A7"), _ALL,
            "prediction deposited twice", _double_output),
-    Mutant("bad_label", ("A6",), _ALL, "prediction replaced by label 7", _bad_label),
+    Mutant("bad_label", ("A6",), _ALL, "prediction replaced by a label outside the domain", _bad_label),
     Mutant("overlap", ("B1", "B4"), _ALL,
            "dormant leaf enabled next to the live one", _overlap),
     Mutant("hidden_overlap", ("B4",), _ALL,

{pyruleanalyzer-2.1.0 → pyruleanalyzer-2.1.2}/pyruleanalyzer/gbdt_analyzer.py

@@ -250,7 +250,7 @@ class GBDTAnalyzer:
         X=None,
         y=None,
         remove_below_n_classifications: int = -1,
-        refine_between_trees: bool = False,
+        refine_between_trees: bool = True,
         save_final_model: bool = True,
         save_report: bool = True,
         max_error_increase: Optional[int] = None,
@@ -270,6 +270,10 @@ class GBDTAnalyzer:
             y: True labels.
             remove_below_n_classifications: Threshold for low-usage refinement
                 (-1 disables).
+            refine_between_trees: After the low-usage stage, merge the rules of
+                different stages of one class that cover the same region into
+                one rule carrying the sum of their values; the other stages
+                add 0 there, so predictions are unchanged. Default True.
             save_final_model: Whether to save the final model to 'final_model.pkl'.
                 Default is True.
             save_report: Whether to save the analysis report to 'output_classifier_gbdt.txt'.

{pyruleanalyzer-2.1.0 → pyruleanalyzer-2.1.2}/pyruleanalyzer/pyruleanalyzer.py

@@ -750,7 +750,7 @@ class PyRuleAnalyzer(ClassifierMixin, BaseEstimator):
         remove_below_n_classifications: int = -1,
         save_final_model: bool = False,
         save_report: bool = False,
-        refine_between_trees: bool = False,
+        refine_between_trees: Optional[bool] = None,
         max_error_increase: Optional[int] = None,
         usage_engine: str = 'auto',
     ) -> Dict[str, Any]:
@@ -773,7 +773,8 @@ class PyRuleAnalyzer(ClassifierMixin, BaseEstimator):
                 redundancy; the merged rule carries the sum of their values,
                 so the score is unchanged). Refused for Random Forest, where
                 it would change the soft vote; no effect on a Decision Tree.
-                Default is False.
+                None (default) turns it on for Gradient Boosting and off
+                otherwise.
             max_error_increase: Error-aware refinement: remove a low-usage
                 rule only while the refinement-set errors stay within this
                 many samples of those before the stage (0 = never more
@@ -798,6 +799,9 @@ class PyRuleAnalyzer(ClassifierMixin, BaseEstimator):
             >>> print(f"Removed {stats['rules_removed']} rules ({stats['reduction_percent']:.1f}%)")
         """
         rules_before = len(self.classifier.initial_rules)
+        if refine_between_trees is None:
+            refine_between_trees = (self.classifier.algorithm_type
+                                    == 'Gradient Boosting Decision Trees')
         
         # Execute refinement using the appropriate analyzer
         # The analyzer handles save_final_model and save_report internally

{pyruleanalyzer-2.1.0 → pyruleanalyzer-2.1.2/pyruleanalyzer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyruleanalyzer
-Version: 2.1.0
+Version: 2.1.2
 Summary: Extract, refine and formally verify the rules of scikit-learn decision trees, random forests and gradient boosting, and export them as standalone Python, C and Arduino classifiers
 Author: GrupoCybersegurancaVirtus
 License-Expression: MIT
@@ -281,15 +281,15 @@ works for all three model types.
 | **Usage count** | Runs the refinement samples through the rules and counts how often each fires. | unchanged |
 | **Boundary merge** | Sibling leaves with the same output and complementary conditions (`<= T` and `> T`) are merged into their parent, repeatedly, until no pair is left. The merged rule carries the sum of the two usage counts. | unchanged |
 | **Low-usage removal** | Rules used `remove_below_n_classifications` times or fewer are removed, deepest first; the sibling of a removed rule is promoted. `-1` disables it, `0` removes only never-used rules. | may change |
-| **Inter-tree fusion** (GBDT, `refine_between_trees=True`) | Stages of one class with an identical region are folded into one rule whose contribution is the sum. The other stages abstain there. | unchanged |
+| **Inter-tree fusion** (GBDT, on by default; `refine_between_trees=False` turns it off) | Stages of one class with an identical region are folded into one rule whose contribution is the sum. The other stages abstain there. | unchanged |
 
 ```python
 # Random Forest: low-usage removal only (see below for why not inter-tree).
 model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1)
 
-# Gradient Boosting: also fold identical stages.
-model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1,
-                              refine_between_trees=True)
+# Gradient Boosting: identical stages are also folded (refine_between_trees,
+# on by default for GBDT).
+model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1)
 ```
 
 Merging siblings is a promotion upwards:
@@ -834,7 +834,7 @@ added condition) refuse NaN as before.
 | `.fit(X, y)` | Train the scikit-learn model and extract its rules |
 | `PyRuleAnalyzer.from_sklearn(model, feature_names=None, class_names=None)` | Wrap an already-fitted `DecisionTreeClassifier`, `RandomForestClassifier`, `ExtraTreesClassifier` (wrapped as a Random Forest; `get_params()["estimator"]` remembers the class, so refitting, also after `clone`, trains an `ExtraTreesClassifier` again) or `GradientBoostingClassifier` |
 | `PyRuleAnalyzer.create(train_path, test_path, model, params, refine)` | Same, from CSV files |
-| `.execute_rule_refinement(X, y, remove_below_n_classifications=-1, refine_between_trees=False, ...)` | Refine; returns `rules_before`, `rules_after`, `rules_removed`, `reduction_percent` |
+| `.execute_rule_refinement(X, y, remove_below_n_classifications=-1, refine_between_trees=None, ...)` | Refine; returns `rules_before`, `rules_after`, `rules_removed`, `reduction_percent` |
 | `.compare_initial_final_results(X, y)` | Metrics and disagreements, initial against refined |
 | `.predict(X, use_refined=True)`, `.predict_proba(X, ...)` | Vectorised prediction |
 | `.summary_report()` | A dict: model type, total rules, classes and every rule |
@@ -960,7 +960,7 @@ cd docs && make html
 
 ## Status
 
-Version 2.1.0; [CHANGELOG.md](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/CHANGELOG.md)
+Version 2.1.2; [CHANGELOG.md](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/CHANGELOG.md)
 says what changed. The figures on this page are drawn from real runs by
 [`docs/figures/make_figures.py`](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/docs/figures/make_figures.py).
 

{pyruleanalyzer-2.1.0 → pyruleanalyzer-2.1.2}/tests/test_cpn_profile.py

@@ -87,3 +87,34 @@ def test_the_askctl_script_is_written(tmp_path):
     decl, queries = mc.ml_program()
     assert set(queries) <= set(mc.check().oracle)
     assert "EXIST_UNTIL" in text or "EV(" in text
+
+
+class _StubDoc:
+    """Records the label bad_label writes on the producer's Prediction arc."""
+
+    def __init__(self):
+        self.written = None
+
+    def arcs(self, page, name, direction):
+        return ["a1"]
+
+    def place_of(self, page, arc):
+        return "Prediction"
+
+    def set_inscription(self, arc, text):
+        self.written = text
+
+
+@pytest.mark.parametrize("labels,prediction,expected", [
+    (list(range(8)), [3], "8"),      # 7 would be a valid class here
+    (list(range(19)), [7], "19"),
+    ([], [2], str(2 + 1_000_000)),   # no constant domain (forests)
+])
+def test_bad_label_writes_a_label_outside_the_domain(labels, prediction, expected):
+    from pyruleanalyzer.cpn_mutants import _bad_label
+    doc = _StubDoc()
+    info = {"labels": labels, "prediction": prediction,
+            "producer_page": "Top", "producer": "Decide_3"}
+    assert _bad_label(doc, info)
+    assert doc.written == expected
+    assert labels == [] or int(doc.written) not in labels

{pyruleanalyzer-2.1.0 → pyruleanalyzer-2.1.2}/tests/test_usage_engine.py

@@ -42,7 +42,8 @@ def test_batch_counts_every_leaf_once_per_sample():
     X, y = make_classification(n_samples=300, n_features=5, n_classes=3,
                                n_informative=3, random_state=1)
     sk = GradientBoostingClassifier(n_estimators=8, max_depth=3, random_state=0).fit(X, y)
-    an = _refined(sk, X, y, 'batch')
+    # without inter-tree merging, which moves merged regions out of all but one stage
+    an = _refined(sk, X, y, 'batch', refine_between_trees=False)
     clf = an.classifier
     by_tree = {}
     for r in clf.final_rules: