pyruleanalyzer 2.0.0__tar.gz → 2.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. pyruleanalyzer-2.1.0/PKG-INFO +968 -0
  2. pyruleanalyzer-2.1.0/README.md +926 -0
  3. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyproject.toml +11 -7
  4. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/__init__.py +12 -0
  5. pyruleanalyzer-2.1.0/pyruleanalyzer/_accel.py +347 -0
  6. pyruleanalyzer-2.1.0/pyruleanalyzer/_arrays.py +965 -0
  7. pyruleanalyzer-2.1.0/pyruleanalyzer/_binary_format.py +567 -0
  8. pyruleanalyzer-2.1.0/pyruleanalyzer/_c_export.py +724 -0
  9. pyruleanalyzer-2.1.0/pyruleanalyzer/_engine.py +439 -0
  10. pyruleanalyzer-2.1.0/pyruleanalyzer/_extraction.py +833 -0
  11. pyruleanalyzer-2.1.0/pyruleanalyzer/_labels.py +393 -0
  12. pyruleanalyzer-2.1.0/pyruleanalyzer/_native_python.py +459 -0
  13. pyruleanalyzer-2.1.0/pyruleanalyzer/_pycodegen.py +119 -0
  14. pyruleanalyzer-2.1.0/pyruleanalyzer/_refinement.py +1249 -0
  15. pyruleanalyzer-2.1.0/pyruleanalyzer/_reporting.py +526 -0
  16. pyruleanalyzer-2.1.0/pyruleanalyzer/_rules.py +478 -0
  17. pyruleanalyzer-2.1.0/pyruleanalyzer/_serialization.py +519 -0
  18. pyruleanalyzer-2.1.0/pyruleanalyzer/compositional.py +1441 -0
  19. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpn_mutants.py +33 -9
  20. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpn_profile.py +7 -12
  21. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpn_semantics.py +206 -4
  22. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpn_tools_exporter.py +56 -3
  23. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/dt_analyzer.py +25 -10
  24. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/exporters.py +9 -9
  25. pyruleanalyzer-2.1.0/pyruleanalyzer/footprint.py +608 -0
  26. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/full_pipeline.py +207 -121
  27. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/gbdt_analyzer.py +190 -13
  28. pyruleanalyzer-2.1.0/pyruleanalyzer/model_checker.py +527 -0
  29. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/pyruleanalyzer.py +614 -103
  30. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/rf_analyzer.py +22 -8
  31. pyruleanalyzer-2.1.0/pyruleanalyzer/rule_classifier.py +329 -0
  32. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/verified_pipeline.py +150 -26
  33. pyruleanalyzer-2.1.0/pyruleanalyzer.egg-info/PKG-INFO +968 -0
  34. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer.egg-info/SOURCES.txt +28 -2
  35. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer.egg-info/requires.txt +4 -4
  36. pyruleanalyzer-2.1.0/tests/test_cheap_fixes.py +325 -0
  37. pyruleanalyzer-2.1.0/tests/test_compositional.py +219 -0
  38. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_coverage_and_precision.py +29 -2
  39. pyruleanalyzer-2.1.0/tests/test_cpn_safe_eval.py +290 -0
  40. pyruleanalyzer-2.1.0/tests/test_engine_hardening.py +447 -0
  41. pyruleanalyzer-2.1.0/tests/test_footprint.py +195 -0
  42. pyruleanalyzer-2.1.0/tests/test_full_pipeline.py +196 -0
  43. pyruleanalyzer-2.1.0/tests/test_json_serialization.py +481 -0
  44. pyruleanalyzer-2.1.0/tests/test_labels_and_nan.py +652 -0
  45. pyruleanalyzer-2.1.0/tests/test_refinement_v2.py +267 -0
  46. pyruleanalyzer-2.1.0/tests/test_regressions.py +286 -0
  47. pyruleanalyzer-2.1.0/tests/test_sklearn_api.py +184 -0
  48. pyruleanalyzer-2.1.0/tests/test_usage_engine.py +83 -0
  49. pyruleanalyzer-2.1.0/tests/test_verified_pipeline_gate.py +187 -0
  50. pyruleanalyzer-2.0.0/PKG-INFO +0 -1110
  51. pyruleanalyzer-2.0.0/README.md +0 -1069
  52. pyruleanalyzer-2.0.0/pyruleanalyzer/_accel.py +0 -176
  53. pyruleanalyzer-2.0.0/pyruleanalyzer/model_checker.py +0 -224
  54. pyruleanalyzer-2.0.0/pyruleanalyzer/parsers.py +0 -272
  55. pyruleanalyzer-2.0.0/pyruleanalyzer/rule_classifier.py +0 -5338
  56. pyruleanalyzer-2.0.0/pyruleanalyzer.egg-info/PKG-INFO +0 -1110
  57. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/LICENSE +0 -0
  58. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/_tree_traversal.c +0 -0
  59. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpn_statespace.py +0 -0
  60. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpntools_oracle.py +0 -0
  61. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer.egg-info/dependency_links.txt +0 -0
  62. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer.egg-info/entry_points.txt +0 -0
  63. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer.egg-info/top_level.txt +0 -0
  64. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/setup.cfg +0 -0
  65. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/setup.py +0 -0
  66. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_export.py +0 -0
  67. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile.py +0 -0
  68. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile_counterexamples.py +0 -0
  69. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile_generic.py +0 -0
  70. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile_oracle.py +0 -0
  71. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile_reduction.py +0 -0
  72. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile_structural.py +0 -0
  73. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_dt_invariants.py +0 -0
  74. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_gbdt_invariants.py +0 -0
  75. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_model_checker.py +0 -0
  76. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_predict_batch.py +0 -0
  77. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_rf_invariants.py +0 -0
  78. {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_rule_fidelity.py +0 -0
@@ -0,0 +1,968 @@
1
+ Metadata-Version: 2.4
2
+ Name: pyruleanalyzer
3
+ Version: 2.1.0
4
+ 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
5
+ Author: GrupoCybersegurancaVirtus
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer
8
+ Project-URL: Documentation, https://grupocybersegurancavirtus.github.io/pyruleanalyzer/
9
+ Project-URL: Changelog, https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/CHANGELOG.md
10
+ Project-URL: Issues, https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/issues
11
+ Keywords: scikit-learn,decision tree,random forest,gradient boosting,rule extraction,explainability,petri nets,model checking,arduino,embedded
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Programming Language :: C
24
+ Classifier: Operating System :: OS Independent
25
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
26
+ Requires-Python: >=3.9
27
+ Description-Content-Type: text/markdown
28
+ License-File: LICENSE
29
+ Requires-Dist: numpy>=1.21
30
+ Requires-Dist: pandas>=1.3
31
+ Requires-Dist: scikit-learn>=1.0
32
+ Requires-Dist: matplotlib
33
+ Requires-Dist: cpncheck>=0.2.2
34
+ Provides-Extra: test
35
+ Requires-Dist: pytest; extra == "test"
36
+ Provides-Extra: docs
37
+ Requires-Dist: sphinx; extra == "docs"
38
+ Requires-Dist: sphinx-autobuild; extra == "docs"
39
+ Requires-Dist: sphinx_rtd_theme; extra == "docs"
40
+ Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
41
+ Dynamic: license-file
42
+
43
+ # pyRuleAnalyzer
44
+
45
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
46
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
47
+ [![PyPI version](https://img.shields.io/pypi/v/pyruleanalyzer.svg)](https://pypi.org/project/pyruleanalyzer/)
48
+
49
+ **Turn a scikit-learn tree model into rules you can read, shrink, verify and
50
+ ship to a microcontroller -- with the same predictions all the way.**
51
+
52
+ A Decision Tree, Random Forest or Gradient Boosting model is a black box until
53
+ someone writes down what it does. pyRuleAnalyzer writes it down: every
54
+ root-to-leaf path becomes a rule. It then removes the rules that add nothing,
55
+ exports the model as a standalone Python, binary or C file (or a complete
56
+ Arduino/ESP32 sketch), and can prove -- with a Petri net and a model checker --
57
+ that the simplified model still behaves like a classifier.
58
+
59
+ ![From a scikit-learn model to rules, a refined model, standalone exports, and an optional verification and deployment](https://raw.githubusercontent.com/GrupoCybersegurancaVirtus/pyruleanalyzer/main/docs/figures/pipeline.png)
60
+
61
+ * **Rules, not a black box.** Each decision path is a rule with its conditions,
62
+ its class and how often it fired.
63
+ * **Refinement that keeps its promises.** Merge redundant sibling leaves, fold
64
+ identical boosting stages, drop rarely used rules -- and keep the rule set a
65
+ clean partition of the feature space.
66
+ * **One answer everywhere.** The in-memory engines, the Python, binary and C
67
+ exports and the Petri net all compute the same function as scikit-learn,
68
+ checked sample by sample at every threshold.
69
+ * **Fast and small.** A vectorised C extension predicts roughly on par with
70
+ scikit-learn on a 100-tree forest; the binary and C exports are half its
71
+ pickle size.
72
+ * **Verified, not just tested.** The model becomes a Hierarchical Coloured
73
+ Petri Net that [CPNCheck](https://github.com/GrupoCybersegurancaVirtus/cpncheck)
74
+ explores. A refinement that breaks the model is stopped before anything is
75
+ exported.
76
+ * **To the edge.** Arduino and ESP32 sketches, board memory estimates,
77
+ hardware-in-the-loop tests and a sensor simulator that runs the sketch on
78
+ your PC.
79
+
80
+ **Contents:**
81
+ [Install](#install) ·
82
+ [A five-minute tour](#a-five-minute-tour) ·
83
+ [The ideas in one page](#the-ideas-in-one-page) ·
84
+ [How each model decides](#how-each-model-decides) ·
85
+ [Refinement](#refinement) ·
86
+ [Predict](#predict-fast) ·
87
+ [Export](#export-standalone-classifiers) ·
88
+ [Arduino and ESP32](#arduino-and-esp32) ·
89
+ [Formal verification](#formal-verification) ·
90
+ [Verified pipeline](#the-verified-pipeline) ·
91
+ [Edit and customise](#edit-and-customise) ·
92
+ [API reference](#api-reference) ·
93
+ [Project layout](#project-layout) ·
94
+ [Status](#status)
95
+
96
+ ## Install
97
+
98
+ ```bash
99
+ pip install pyruleanalyzer
100
+ ```
101
+
102
+ Or from source, for development:
103
+
104
+ ```bash
105
+ git clone https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer.git
106
+ cd pyruleanalyzer
107
+ pip install -e .
108
+ ```
109
+
110
+ Python 3.9 or later. Dependencies: `numpy`, `pandas`, `scikit-learn`,
111
+ `matplotlib` and [`cpncheck`](https://pypi.org/project/cpncheck/) (pure Python,
112
+ the model checker for the exported nets).
113
+
114
+ **The C extension.** Batch prediction uses a compiled extension. The wheels on
115
+ PyPI ship it for Linux (x86_64, aarch64), macOS (Intel and Apple silicon) and
116
+ Windows (64-bit), Python 3.9 to 3.14 (not the free-threaded 3.14t build), so
117
+ `pip install` needs no compiler.
118
+ Elsewhere pip builds from source when a C compiler exists, and otherwise falls
119
+ back to numpy -- slower, same answers:
120
+
121
+ ```python
122
+ from pyruleanalyzer._accel import HAS_C_EXTENSION
123
+ print(HAS_C_EXTENSION) # True when the compiled extension is active
124
+ ```
125
+
126
+ ## A five-minute tour
127
+
128
+ ### 1. A tree and its rules
129
+
130
+ Wine again, two features to keep the picture small. Train an ordinary
131
+ decision tree through pyRuleAnalyzer and ask for its rules:
132
+
133
+ ```python
134
+ from sklearn.datasets import load_wine
135
+ from sklearn.model_selection import train_test_split
136
+ from pyruleanalyzer import PyRuleAnalyzer
137
+
138
+ X, y = load_wine(return_X_y=True, as_frame=True)
139
+ X = X[["proline", "flavanoids"]]
140
+ X_train, X_test, y_train, y_test = train_test_split(
141
+ X, y, test_size=0.3, random_state=0, stratify=y)
142
+ # Rule usage is measured on a split of its own, so the test set stays unseen
143
+ # by every step that changes the model.
144
+ X_train, X_val, y_train, y_val = train_test_split(
145
+ X_train, y_train, test_size=0.3, random_state=0, stratify=y_train)
146
+
147
+ model = PyRuleAnalyzer.new_model("Decision Tree", {"random_state": 0})
148
+ model.fit(X_train, y_train)
149
+ print(model) # PyRuleAnalyzer(model=Decision Tree, features=2, classes=3, rules=8)
150
+ ```
151
+
152
+ A tree is a series of if/else splits; each path from the root to a leaf is one
153
+ rule -- a list of conditions and the class the leaf predicts. On the iris
154
+ flowers, a depth-3 tree gives these five rules:
155
+
156
+ ![An iris decision tree on the left; the five rules extracted from it on the right, one per leaf](https://raw.githubusercontent.com/GrupoCybersegurancaVirtus/pyruleanalyzer/main/docs/figures/rules.png)
157
+
158
+ For a **Random Forest** the rules of every tree are extracted. For a
159
+ **Gradient Boosting** model each leaf also carries the value that its boosting
160
+ stage adds to the score.
161
+
162
+ ### 2. Refine
163
+
164
+ Eight rules is more than this problem needs. Refinement merges the leaves that
165
+ split for no reason and drops the rules that almost no sample reaches:
166
+
167
+ ```python
168
+ stats = model.execute_rule_refinement(
169
+ X=X_val, y=y_val, remove_below_n_classifications=1)
170
+ print(stats)
171
+ # {'rules_before': 8, 'rules_after': 3, 'rules_removed': 5, 'reduction_percent': 62.5}
172
+
173
+ print((model.predict(X_test, use_refined=False) == y_test).mean()) # 0.833 initial
174
+ print((model.predict(X_test) == y_test).mean()) # 0.852 refined
175
+ ```
176
+
177
+ ![The decision regions of the wine tree: eight boxes before refinement, three after; the boxes never overlap](https://raw.githubusercontent.com/GrupoCybersegurancaVirtus/pyruleanalyzer/main/docs/figures/refinement.png)
178
+
179
+ Each rule is a box in the feature space, coloured by its class. Refinement
180
+ makes the boxes fewer and larger; the boxes of one tree still cover the space
181
+ without overlapping, which is the property that keeps every engine in
182
+ agreement. (Test accuracy moved by one sample out of 54 here. Refinement trades
183
+ a little fidelity for a much simpler model; always measure it on data the
184
+ refinement did not see.)
185
+
186
+ ### 3. Read what is left
187
+
188
+ ```python
189
+ report = model.summary_report()
190
+ for rule in report["rules"]:
191
+ print(rule["name"], "->", rule["class"], rule["conditions"])
192
+ # Rule0_Class2_promoted -> 2 ['flavanoids <= 1.425000011920929']
193
+ # Rule3_Class1 -> 1 ['flavanoids > 1.425000011920929', 'proline <= 765.0']
194
+ # Rule7_Class0_promoted -> 0 ['flavanoids > 1.425000011920929', 'proline > 765.0']
195
+ ```
196
+
197
+ Three rules a person can read: low flavanoids means class 2; otherwise
198
+ proline above 765 means class 0 and the rest class 1. A name ending in
199
+ `_promoted` is a rule that absorbed the region of a sibling that was removed;
200
+ `_&_` marks merged siblings.
201
+
202
+ ### 4. Ask the model checker
203
+
204
+ ```python
205
+ results = model.model_check(which="both", samples=X_test.iloc[:1],
206
+ test_samples=X_test)
207
+ ```
208
+
209
+ The rules become a Petri net, [CPNCheck](https://github.com/GrupoCybersegurancaVirtus/cpncheck)
210
+ explores it, and 13 properties are checked on the initial model and on the
211
+ refined one. The comparison is the acceptance test of the refinement:
212
+
213
+ ![The comparison table printed by model_check(which='both'): every property PASS before and after refinement](https://raw.githubusercontent.com/GrupoCybersegurancaVirtus/pyruleanalyzer/main/docs/figures/comparison.png)
214
+
215
+ *(The figure shows a small boosting model, which has more properties than a
216
+ single tree.)* See [Formal verification](#formal-verification) for what each
217
+ one says.
218
+
219
+ ### 5. Ship it
220
+
221
+ ```python
222
+ model.to_python("wine_classifier.py") # no dependencies
223
+ model.to_binary("wine.bin") # compact, loads without scikit-learn
224
+ model.to_c_header("wine.h") # predict() in plain C
225
+ ```
226
+
227
+ For a board, `verified_pipeline()` also writes the sketch and, with
228
+ `arduino-cli`, uploads it -- see [Arduino and ESP32](#arduino-and-esp32).
229
+
230
+ ## The ideas in one page
231
+
232
+ | Term | Meaning |
233
+ |---|---|
234
+ | **Rule** | One root-to-leaf path: conditions on features, plus the leaf's output. |
235
+ | **Region (box)** | The set of inputs a rule's conditions select. |
236
+ | **Partition** | The rules of a tree cover the feature space and their regions never overlap, so exactly one rule fires per input. |
237
+ | **Boundary redundancy** | Sibling leaves that split on the same threshold and give the same output; the split is useless. |
238
+ | **Sibling promotion** | When a rule is removed, its sibling takes over the parent's region. |
239
+ | **Usage count** | How many samples of the refinement set reach a rule; carried through merges and promotions. |
240
+ | **Semantic redundancy** | Boosting stages with identical regions: they are folded into one rule that adds both contributions. |
241
+ | **HCPN** | Hierarchical Coloured Petri Net: the model written as places, transitions and guards, in the file format CPN Tools opens. |
242
+ | **Occurrence graph** | Every marking the net can reach from the input; what the model checker explores. |
243
+ | **Property (A1-D2, PC)** | A question put to the net: does it always decide, never decide twice, never overlap, agree with the model? |
244
+ | **Gate** | A refinement that breaks a property that held before is refused, and nothing is exported. |
245
+
246
+ ## How each model decides
247
+
248
+ Every engine -- the in-memory classifier, the vectorised batch predictor, the
249
+ exported Python, binary and C files and the Petri net -- computes the same
250
+ function, for the initial and for the refined rule set:
251
+
252
+ ![One sample through a decision tree (the one rule that matches), a random forest (summed per-tree distributions, argmax) and a boosting model (initial score plus each stage's contribution, sign of the score)](https://raw.githubusercontent.com/GrupoCybersegurancaVirtus/pyruleanalyzer/main/docs/figures/strategies.png)
253
+
254
+ * **Decision Tree**: the sample goes to the one rule whose region contains it;
255
+ its class is the answer. With no matching rule (a rule set edited by hand
256
+ or a custom refinement that left a region uncovered) the model falls back to
257
+ its default class.
258
+ * **Random Forest**: each tree answers with a class distribution; the
259
+ distributions are normalised and summed, and the largest wins (lowest class
260
+ index on a tie). A tree with no matching rule abstains.
261
+ * **Gradient Boosting**: the initial score plus the contribution
262
+ (`learning_rate * leaf_value`) of the matching leaf of every stage. Binary
263
+ models decide on `score >= 0`, exactly as scikit-learn does; multiclass
264
+ models take the argmax over the class channels.
265
+
266
+ **Precision matters.** scikit-learn casts inputs to `float32` before comparing
267
+ them with the thresholds. Models built with `fit()` or `from_sklearn()` do the
268
+ same (`input_dtype='float32'`), and so do the exports, so a value one ULP above
269
+ a threshold goes to the same side as in scikit-learn.
270
+ [`tests/test_rule_fidelity.py`](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/tests/test_rule_fidelity.py)
271
+ compares every engine, including the compiled C header, against a reference
272
+ implementation on samples placed on and one ULP around every threshold.
273
+
274
+ ## Refinement
275
+
276
+ `execute_rule_refinement()` runs the passes below, in this order. The same call
277
+ works for all three model types.
278
+
279
+ | Pass | What it does | Predictions |
280
+ |---|---|---|
281
+ | **Usage count** | Runs the refinement samples through the rules and counts how often each fires. | unchanged |
282
+ | **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 |
283
+ | **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 |
284
+ | **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 |
285
+
286
+ ```python
287
+ # Random Forest: low-usage removal only (see below for why not inter-tree).
288
+ model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1)
289
+
290
+ # Gradient Boosting: also fold identical stages.
291
+ model.execute_rule_refinement(X=X_val, y=y_val, remove_below_n_classifications=1,
292
+ refine_between_trees=True)
293
+ ```
294
+
295
+ Merging siblings is a promotion upwards:
296
+
297
+ ```
298
+ BEFORE AFTER
299
+ ------ -----
300
+ v1 <= 3.5 v1 <= 3.5
301
+ |-- v2 <= 1.2 -> class 0 => -> class 0 (the v2 split
302
+ `-- v2 > 1.2 -> class 0 told nothing)
303
+ ```
304
+
305
+ Removing a rule never leaves an uncovered region in a Decision Tree or a
306
+ Random Forest. When the sibling of the removed rule is a leaf, it is promoted
307
+ the same way; when the sibling is a sub-branch, the sub-branch is raised into
308
+ the parent's place (its rules drop the parent's split, are renamed
309
+ `..._grafted`, and keep their outputs), so each tree still answers everywhere.
310
+ In Gradient Boosting a removed region whose sibling is a sub-branch makes that
311
+ stage add 0.0 to the score there: the other stages and the initial score still
312
+ decide. Usage and error counts are recounted on the refinement set afterwards.
313
+
314
+ **Error-aware removal.** `max_error_increase=k` removes a low-usage rule only
315
+ while the refinement set's misclassifications stay within `k` of those before
316
+ the stage; `0` never adds an error (reduced-error pruning when combined with a
317
+ very large `remove_below_n_classifications`). `None`, the default, uses usage
318
+ alone. A small refinement set can make it overfit: measure on fresh data.
319
+
320
+ **Large refinement sets (Gradient Boosting).** `usage_engine='auto'`, the
321
+ default, counts how many refinement samples reach each rule by pushing them
322
+ through the compiled tree arrays, before and after low-usage removal, instead
323
+ of classifying them one at a time. The refined rules are identical; on 288 000
324
+ samples and 51 000 rules refinement takes 25 s instead of 2.5 h.
325
+ `usage_engine='loop'` forces the per-sample path, `'batch'` refuses to fall
326
+ back to it.
327
+
328
+ * **Random Forest refuses inter-tree fusion** (with a `RuntimeWarning`): its
329
+ prediction is the average of one distribution per tree, so removing a voter
330
+ changes the average.
331
+ * **Measure on fresh data.** Usage counts come from the data passed to the
332
+ refinement. Evaluate the refined model on a different split, or the accuracy
333
+ you see is optimistic.
334
+ * `compare_initial_final_results(X=..., y=...)` prints accuracy, precision,
335
+ recall, F1, a confusion matrix, the structural complexity score and the
336
+ samples on which the two models disagree.
337
+
338
+ ### Custom refinement
339
+
340
+ Supply your own rule to remove, from domain knowledge:
341
+
342
+ ```python
343
+ def drop_short_rules(rules):
344
+ # Keep only rules with at least two conditions; report the others as removed.
345
+ kept = [r for r in rules if len(r.conditions) >= 2]
346
+ removed = [(r, r) for r in rules if len(r.conditions) < 2]
347
+ return kept, removed
348
+
349
+ model.classifier.set_custom_rule_removal(drop_short_rules)
350
+ new_rules, removed = model.classifier.adjust_and_remove_rules("custom")
351
+ ```
352
+
353
+ ## Predict fast
354
+
355
+ `predict()` and `predict_proba()` take a DataFrame or a 2-D array and run on
356
+ compiled tree arrays: the rules are turned into flat numpy arrays once, and
357
+ every sample is pushed through them in a single vectorised pass -- in C when
358
+ the extension is available, in numpy otherwise. `use_refined=False` answers
359
+ with the initial rules.
360
+
361
+ ```python
362
+ labels = model.predict(X_test)
363
+ proba = model.predict_proba(X_test) # shape (n_samples, n_classes)
364
+ initial = model.predict(X_test, use_refined=False)
365
+ ```
366
+
367
+ ![Throughput of scikit-learn, pyRuleAnalyzer with the C extension, with the numpy fallback and the exported Python file; and the size on disk of the scikit-learn pickle, the exported .py, .bin and .h](https://raw.githubusercontent.com/GrupoCybersegurancaVirtus/pyruleanalyzer/main/docs/figures/benchmark.png)
368
+
369
+ The figure is measured by
370
+ [`docs/figures/make_figures.py`](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/docs/figures/make_figures.py)
371
+ on a 100-tree Random Forest (depth <= 10, 20 features, 10 000 test samples,
372
+ one thread). Read it as an order of magnitude, not a promise; run your own
373
+ model with the scripts in `examples/`:
374
+
375
+ * the C extension is **roughly on par with scikit-learn** `predict` (1.04x on
376
+ the machine the figure was last measured on; the ratio depends on the
377
+ machine, the compiler and the model);
378
+ * the numpy fallback is about a third of scikit-learn's speed;
379
+ * the exported `.py` is meant to run **without** this package or scikit-learn,
380
+ one sample at a time -- not to compete with vectorised code;
381
+ * the `.bin` and `.h` files are about half the size of the scikit-learn pickle;
382
+ the generated `.py` is *larger* than the pickle for a forest this size.
383
+
384
+ Single samples go through `model.classifier.classify(sample_dict, final=True)`
385
+ and return `(class, votes, probabilities)`.
386
+
387
+ ## Export standalone classifiers
388
+
389
+ | Method | Writes | Needs at run time |
390
+ |---|---|---|
391
+ | `to_python(path)` | nested `if/else` Python, one function `predict(sample)` | nothing (GBDT: `math`) |
392
+ | `to_binary(path)` | compact tree arrays (magic `PYRA`, versioned) | this package, to load; not scikit-learn |
393
+ | `to_c_header(path)` | const arrays and a `predict(const double *features)` function in C | a C compiler |
394
+ | `export(base_name, formats=[...])` | any of the above, plus `"cpn"`, under `files/` | -- |
395
+
396
+ ```python
397
+ from pyruleanalyzer import PyRuleAnalyzer
398
+
399
+ model.to_binary("wine.bin")
400
+ loaded = PyRuleAnalyzer.load_binary("wine.bin") # arrays only, no scikit-learn
401
+ labels = loaded.classifier.predict_batch(X_test.values, list(X_test.columns))
402
+ ```
403
+
404
+ ```python
405
+ # wine_classifier.py, as generated for the refined wine tree
406
+ def _predict(sample):
407
+ if sample.get('flavanoids', 0) <= 1.425000011920929:
408
+ return 2
409
+ else:
410
+ if sample.get('proline', 0) <= 765.0:
411
+ return 1
412
+ else:
413
+ return 0
414
+
415
+
416
+ def predict(sample):
417
+ return _predict({k: _f32(v) for k, v in sample.items()}) # float32, as scikit-learn
418
+ ```
419
+
420
+ A loaded `.bin` supports batch prediction but has no `Rule` objects, so it
421
+ cannot be refined or edited. `export(..., use_refined=False)` exports the
422
+ initial rules instead of the refined ones.
423
+
424
+ ## Arduino and ESP32
425
+
426
+ A complete, ready-to-upload sketch comes from the same model:
427
+
428
+ ```python
429
+ model.classifier.export_to_arduino_ino("model.ino", board_model="uno")
430
+ ```
431
+
432
+ or in one call from a CSV, with a memory check:
433
+
434
+ ```python
435
+ from pyruleanalyzer import full_pipeline
436
+
437
+ results = full_pipeline(
438
+ train_csv="train.csv", target_feature="Target",
439
+ model_type="Decision Tree", max_depth=10,
440
+ generate_arduino_sketch=True, board_model="uno", # or 'auto'
441
+ serial_baud=115200,
442
+ )
443
+ print(results["generated_files"]["arduino"]) # path to model.ino
444
+ print(results["memory_check"]) # flash / RAM against the board
445
+ ```
446
+
447
+ `full_pipeline()` refines on a validation split held out from the training
448
+ data (`validation_size=0.2`), never on the test CSV. A test CSV is matched to
449
+ the training columns by name; one without the target column is ignored with a
450
+ warning. String labels are encoded with one `LabelEncoder` for both files
451
+ (`results["label_classes"]` maps the codes back), and missing values are
452
+ filled with 0 with a warning.
453
+
454
+ The sketch is self-contained: the tree arrays are inline, `pyra_predict()` is
455
+ plain C, `setup()` prints the model's metadata and `loop()` reads the features,
456
+ predicts and prints JSON on the serial port. `read_features()` is the one place
457
+ you edit -- it ships with `TODO` placeholders for your sensors:
458
+
459
+ ```cpp
460
+ void read_features(void) {
461
+ features[0] = 0.0; // TODO: read sensor 1
462
+ features[1] = 0.0; // TODO: read sensor 2
463
+ }
464
+
465
+ void loop(void) {
466
+ read_features();
467
+ int32_t result = pyra_predict((const double*)features);
468
+ Serial.print(F("{\"class\":"));
469
+ Serial.print(result);
470
+ Serial.println("}");
471
+ delay(1000);
472
+ }
473
+ ```
474
+
475
+ The tool estimates flash and SRAM and compares them with the target board
476
+ (`uno`, `nano`, `mega`, `leonardo`, `esp32`), warning with `OVER!` when the
477
+ model will not fit. For depth strategies, feature selection and memory formulas
478
+ see the
479
+ [modelling guide](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/docs/tutorials/modeling_for_arduino.rst).
480
+
481
+ **Size the model for the board before training.** `pyruleanalyzer.footprint`
482
+ bounds the flash an exported model needs from its hyperparameters alone, so the
483
+ largest model a board holds can be chosen up front:
484
+
485
+ ```python
486
+ from pyruleanalyzer import BOARDS, estimate_footprint, fit_to_board, suggest_complexity
487
+
488
+ estimate_footprint('gbdt', n_estimators=50, n_classes=8, max_leaf_nodes=127)
489
+ # {'trees': 400, 'leaves': 50800, 'nodes': 101200, 'model_bytes': 2861600, ...}
490
+
491
+ print(suggest_complexity(algorithm='gbdt', n_estimators=50, n_classes=8,
492
+ depths=range(3, 9), board='esp32_huge_app'))
493
+
494
+ fit = fit_to_board(X_train, y_train, board='esp32_huge_app') # or flash_bytes=..., ram_bytes=...
495
+ model = GradientBoostingClassifier(**fit.params).fit(X_train, y_train)
496
+ ```
497
+
498
+ `fit_to_board()` gives each candidate number of trees the most leaves per tree
499
+ that fit, scores the candidates on held-out training rows and returns the best
500
+ (`fit.candidates` lists them all). Presets: `uno`, `nano`, `mega2560`, `esp32`
501
+ (1.25 MB application) and `esp32_huge_app` (3 MB); any board can be described
502
+ with `flash_bytes` and `ram_bytes`. The ESP32 constants are measured on the
503
+ Arduino core 3.3.12, where the bound was within 15 KB above the compiled size.
504
+
505
+ **Test it without a board, or with one:**
506
+
507
+ | Script | What it checks |
508
+ |---|---|
509
+ | `examples/arduino_example.py` | trains on Iris/Wine and writes the sketch for a chosen board |
510
+ | `examples/arduino_hardware_test.py` | hardware in the loop: compiles, uploads, sends vectors over serial and compares the board's answers (and latency) with the PC's |
511
+ | `examples/arduino_sensor_simulation.py` | runs the **production sketch** (`setup()`/`loop()` as generated) on the PC with g++ and an Arduino shim, over time-varying signals -- synthetic regimes or a replay of your test set -- through the ADC or the serial port |
512
+
513
+ The simulator found two things worth knowing before you flash: a 10-bit linear
514
+ ADC destroys long-tailed features, and a 64-byte serial RX buffer with a
515
+ `delay()` in `loop()` silently drops lines longer than the buffer.
516
+
517
+ ## Formal verification
518
+
519
+ Accuracy tells you the model is usually right. It does not tell you the
520
+ *refinement* left a model that still behaves like a classifier: overlapping
521
+ rules tend to agree on the class, so a broken rule set can keep its accuracy.
522
+ pyRuleAnalyzer therefore turns the rules into a **Hierarchical Coloured Petri
523
+ Net** in the native format of [CPN Tools](https://cpntools.org) 4.x, and checks
524
+ the net.
525
+
526
+ ```python
527
+ model.export_hcpn("wine", which="both", sample=X_test.iloc[0])
528
+ # files/wine_initial.cpn and files/wine_final.cpn
529
+ ```
530
+
531
+ ![The three nets: a decision tree is one page with a transition per rule; a random forest has a substitution transition per tree and a Vote; a boosting model has a channel per class with a stage per tree and a Decide](https://raw.githubusercontent.com/GrupoCybersegurancaVirtus/pyruleanalyzer/main/docs/figures/hcpn.png)
532
+
533
+ The names are the ones in the files. A *place* holds tokens (here the input
534
+ sample, per-tree scores, the prediction); a *transition* fires when its guard
535
+ holds on the tokens it consumes. A decision-tree leaf is a transition whose
536
+ guard is the path's condition; the double-bordered boxes are *substitution
537
+ transitions*, each standing for a page of its own. The nets implement the
538
+ constructions proved in the accompanying article (*Coloured Petri Nets-Based
539
+ Modeling and Validation of Gradient Boosting Decision Trees*): one transition
540
+ per root-to-leaf path with exactly one enabled per sample (Theorem 1), and the
541
+ sequential accumulation `s + eta * v` along the stages of each class channel
542
+ (Theorem 2). The files open directly in CPN Tools for visualisation and
543
+ simulation.
544
+
545
+ ### What gets checked
546
+
547
+ ```python
548
+ from pyruleanalyzer import check_cpn
549
+
550
+ result = check_cpn("files/wine_final.cpn", class_labels=[0, 1, 2],
551
+ samples=X_test.iloc[:1],
552
+ classifier=model.classifier, test_samples=X_test)
553
+ print(result.report())
554
+ ```
555
+
556
+ ![The model checker's report for a refined boosting model: occurrence graph size, then A1-A8, B1-B4, C1-C3b and PC, all PASS, 17 passed, VERIFIED](https://raw.githubusercontent.com/GrupoCybersegurancaVirtus/pyruleanalyzer/main/docs/figures/terminal.png)
557
+
558
+ Four techniques, reported separately because they establish different things:
559
+
560
+ | Technique | Properties | What a verdict means |
561
+ |---|---|---|
562
+ | **CTL on the occurrence graph** | A1-A7, B1-B3, C1-C3b, D1-D2b | Temporal properties of every execution, **for the input in the initial marking** |
563
+ | **SCC analysis** | A8 home marking | A marking reachable from every marking |
564
+ | **Structural guard analysis** | B4 guard disjointness | The leaves partition the feature space, for **every input** |
565
+ | **Conformance testing** | PC | The net computes the classifier's class on the tested inputs |
566
+
567
+ The main properties (catalogue in `PROPERTY_CATALOG`):
568
+
569
+ | Id | Says |
570
+ |---|---|
571
+ | A1 / A2 | The net terminates, and never gets stuck without an answer |
572
+ | A3 / A4 | A decision is inevitable (`AF`), and always still reachable (`AG EF`) |
573
+ | A5 / A6 | At most one output, and it is a valid label |
574
+ | A7 / A8 | Safeness (at most one token per place); one home marking |
575
+ | B1 / B2 / B3 | Per tree: at most one leaf enabled, one is always selected, one output |
576
+ | **B4** | **No two leaves of a tree overlap, for every input** |
577
+ | C1-C3 | (GBDT) stages in order, no score before the last stage, one decision |
578
+ | D1-D2 | (RF) every tree votes, and the vote is unique |
579
+ | PC | The net's prediction equals the model's |
580
+
581
+ **B4 is the acceptance criterion of a refinement.** B1 is per input: it can
582
+ only see overlaps the tested input reaches. B4 reasons about every input. Here
583
+ a rule loses its last condition (a bug of the kind a refinement could have):
584
+
585
+ ![model_check on a rule set with an overlap: A1-B3 PASS, B4 FAIL with the pair of rules and an input where both hold, PC skipped, VIOLATION FOUND](https://raw.githubusercontent.com/GrupoCybersegurancaVirtus/pyruleanalyzer/main/docs/figures/violation.png)
586
+
587
+ Everything the temporal properties say is about behaviour -- the net decides
588
+ once, with a valid label -- not about being *right*. A net that predicts a
589
+ wrong but valid class passes every CTL property; only PC (net against model)
590
+ catches it.
591
+
592
+ ### Dead markings
593
+
594
+ The checker uses textbook CTL with a self-loop on dead markings, so a run that
595
+ stops before `phi` refutes `AF phi`. CPN Tools' ASK-CTL reads `EV` differently:
596
+ it is vacuously true at a dead marking, so a net that deadlocks before
597
+ predicting satisfies `EV(PRED)`. `model_check(..., askctl=True)` writes the
598
+ CPN Tools query script that asks the same questions, encoding `AF phi` as
599
+ `EV(phi) AND NOT E[not phi U (dead and not phi)]` to remove that gap.
600
+
601
+ ### Big models: state-space reductions
602
+
603
+ The graph of an ensemble is large because its trees fire independently: a
604
+ Random Forest of `n` trees has `2^n + 2` markings, and a `K`-class boosting
605
+ model with `M` stages per class has `(3M+3)^K + 2` (the tests check the
606
+ second formula). Beyond `max_nodes` the state-space properties get no verdict,
607
+ rather than a guess -- they are reported as *not decided*, and an ensemble
608
+ beyond a handful of trees gets there quickly: on a 20-tree Random Forest, 14 of
609
+ the 16 properties were not decided at `max_nodes=50_000`, and a 50-tree forest
610
+ took about 12 minutes.
611
+
612
+ **For ensembles, use compositional verification.** The trees of a forest and
613
+ the channels of a boosting model share nothing but the input, so each one is
614
+ explored on its own (a graph of a few markings per tree) and the vote or
615
+ decision is checked once per combination of their outputs. Every verdict comes
616
+ with the argument that it equals the full graph's (see the model-checking
617
+ tutorial); anything the composition cannot settle falls back to the stubborn
618
+ reduction, and the report says which method decided each property:
619
+
620
+ ```python
621
+ model.model_check(which="final", reduction="compositional")
622
+ ```
623
+
624
+ | Model | Full graph | Compositional |
625
+ |---|---|---|
626
+ | Random Forest, 20 trees | 2^20 + 2 markings, 14 of 16 not decided | 60 markings, 1.4 s, all decided |
627
+ | Random Forest, 50 trees | out of reach | 150 markings, 7 s, all decided |
628
+ | Boosting, 3 classes x 20 stages | 63^3 + 2 markings | 192 markings, 1.4 s, all decided |
629
+
630
+ On small ensembles, where the full graph fits, the compositional and full-graph
631
+ verdicts were compared on 2 128 property checks, mutants included, without a
632
+ mismatch. A single decision tree has nothing to compose and is checked on its
633
+ (small) full graph. Partial-order reduction (stubborn sets) remains available:
634
+
635
+ ```python
636
+ model.model_check(which="final", reduction="stubborn")
637
+ ```
638
+
639
+ Keep in mind what remains when the graph is out of reach: B4 (structural, no
640
+ state space) and PC (conformance, one run per input) are still decided, but
641
+ they largely hold by construction -- the leaves of a scikit-learn tree are
642
+ disjoint and the net is generated from the same rules as the classifier -- so
643
+ on an unmodified model they confirm the export rather than add evidence.
644
+
645
+ A 12-tree forest has 4 098 markings. With the reduction, CPNCheck decides its
646
+ properties on 69 smaller graphs: 68 of them hold 1 020 markings between them,
647
+ and one -- for D2a, the property that observes every leaf -- is still the full
648
+ 4 098. The sweep-line, symmetry and equivalence reductions of CPNCheck pass
649
+ through `reduction_options={...}`.
650
+
651
+ ### Is the checker right?
652
+
653
+ * **Against CPN Tools.** `pyruleanalyzer.cpntools_oracle` runs the CPN Tools
654
+ 4.0.1 simulator headlessly, enters the state-space tool as the GUI does and
655
+ evaluates the ASK-CTL queries. CPNCheck compares its statistics, verdicts
656
+ and ML library with CPN Tools on its own samples and on 48 nets other people
657
+ wrote (details in the CPNCheck README).
658
+ * **Sensitivity.** `pyruleanalyzer.cpn_mutants.make_mutants()` derives one
659
+ mutant per property -- a small edit of a guard, an inscription or an arc that
660
+ makes exactly that property false -- and the tests require every mutant to be
661
+ caught. A checker that always says "true" would agree with CPN Tools on
662
+ correct nets; it would not survive this.
663
+
664
+ ```bash
665
+ pytest tests/test_model_checker.py # properties, mutants, gate
666
+ PYRA_CPNTOOLS=1 pytest tests/test_model_checker.py # + agreement with CPN Tools
667
+ python examples/cpn_tools_crosscheck.py # the full experiment
668
+ python examples/cpncheck_walkthrough.py # an 11-step guided tour
669
+ ```
670
+
671
+ The tree-specific part (the property catalogue, the mutation operators) lives
672
+ here as a plugin, `ml_trees`; CPNCheck itself knows nothing about trees and
673
+ checks any `.cpn` file.
674
+
675
+ ## The verified pipeline
676
+
677
+ `verified_pipeline()` chains the whole flow and makes the verification a
678
+ **gate** instead of a report:
679
+
680
+ ![Train, extract and export the initial net, check, refine, check again; the gate compares the verdicts and either exports and deploys or raises VerificationError](https://raw.githubusercontent.com/GrupoCybersegurancaVirtus/pyruleanalyzer/main/docs/figures/gate.png)
681
+
682
+ ```python
683
+ from pyruleanalyzer import verified_pipeline
684
+
685
+ result = verified_pipeline(
686
+ X=X, y=y, # or train_csv=..., test_csv=...
687
+ model_type="Gradient Boosting Decision Trees",
688
+ params={"n_estimators": 8, "max_depth": 3, "random_state": 42},
689
+ remove_below_n_classifications=1,
690
+ verify_samples=3,
691
+ export_formats=("python", "binary", "c", "arduino"),
692
+ )
693
+
694
+ result["passed"] # every property held on both models
695
+ result["verification"]["final"].report()
696
+ result["exports"]["arduino"] # files/model.ino
697
+ ```
698
+
699
+ With `fail_on_violation=True` (the default) the second check raises
700
+ `VerificationError`, with the failing result attached, instead of exporting a
701
+ model whose net no longer satisfies what the initial one did.
702
+
703
+ A property that could not be decided -- typically because the occurrence graph
704
+ went over `max_nodes` -- is not a pass either. With `fail_on_inconclusive=True`
705
+ (the default) such a stage raises `VerificationError` too; with `False` the
706
+ pipeline goes on, but `result["passed"]` is still `False` and
707
+ `result["inconclusive"]` lists the undecided property ids per stage
708
+ (`{"initial": [...], "final": [...]}`). For ensembles, pass
709
+ `reduction="compositional"` so the properties get a verdict.
710
+
711
+ The refinement counts rule usage on a validation split held out from the
712
+ training data (`validation_size=0.25` by default; its size is reported as
713
+ `result["metrics"]["refinement_rows"]`). The test split is used only for the
714
+ accuracy and the verification, so the reported accuracy is not optimistic.
715
+
716
+ An already-trained estimator skips the training step, and
717
+ `PyRuleAnalyzer.from_sklearn()` does the same wrapping on its own:
718
+
719
+ ```python
720
+ from sklearn.ensemble import RandomForestClassifier
721
+
722
+ # A forest's full state space grows as 2^n_trees; compositional verification
723
+ # checks each tree on its own, so a realistic forest gets every verdict.
724
+ clf = RandomForestClassifier(n_estimators=50, max_depth=6).fit(X_train, y_train)
725
+ result = verified_pipeline(X=X, y=y, sklearn_model=clf,
726
+ reduction="compositional",
727
+ export_formats=("c", "arduino"))
728
+
729
+ analyzer = PyRuleAnalyzer.from_sklearn(clf) # outside the pipeline
730
+ ```
731
+
732
+ To flash the board too, give the pipeline its FQBN and port; it drives
733
+ `arduino-cli`, and reports the exact commands if the CLI is not installed:
734
+
735
+ ```python
736
+ verified_pipeline(..., export_formats=("arduino",),
737
+ deploy_fqbn="arduino:avr:nano", deploy_port="COM3", upload=True)
738
+ ```
739
+
740
+ ```bash
741
+ python examples/verified_pipeline_example.py
742
+ python examples/verified_pipeline_example.py --classes 3 --askctl
743
+ python examples/verified_pipeline_example.py --arduino --fqbn arduino:avr:nano --port COM3 --upload
744
+ ```
745
+
746
+ ## Edit and customise
747
+
748
+ **Edit rules by hand** in a terminal editor -- add or remove conditions, change
749
+ a class, delete a rule:
750
+
751
+ ```python
752
+ model.edit_rules()
753
+ ```
754
+
755
+ **Control what is written to disk.** Everything goes to `files/` (created if it
756
+ does not exist) unless you give a path:
757
+
758
+ | Call | Flag | File | Default |
759
+ |---|---|---|---|
760
+ | `new_classifier()` | `save_initial_model` | `initial_model.pkl` | `True` |
761
+ | `new_classifier()` | `save_sklearn_model` | `sklearn_model.pkl` | `True` |
762
+ | `execute_rule_refinement()` (analyzers) | `save_final_model` | `final_model.pkl` | `True` |
763
+ | `execute_rule_refinement()` (analyzers) | `save_report` | `output_classifier_*.txt` | `True` |
764
+
765
+ `PyRuleAnalyzer.execute_rule_refinement()` defaults both to `False`.
766
+ **Save and load a model.** `model.save_json(path)` and
767
+ `PyRuleAnalyzer.load_json(path)` keep everything needed to go on working with
768
+ it -- initial and refined rules (with their usage counts, leaf values and
769
+ distributions; thresholds read back bit for bit), GBDT metadata, feature and
770
+ class names, hyperparameters -- so a loaded model can be refined again, edited,
771
+ model-checked and exported. `model.save(path)` and `PyRuleAnalyzer.load(path)`
772
+ use this JSON format when the path ends in `.json` and pickle otherwise; both
773
+ recompile the native function on load. The `.bin` export, by contrast, holds
774
+ only the compiled arrays: it predicts, but has no rules to refine or export.
775
+
776
+ ```python
777
+ model.save("files/model.json")
778
+ model = PyRuleAnalyzer.load("files/model.json")
779
+ ```
780
+
781
+ **Security.** Prefer JSON: loading a `.json` model only reads data (a versioned
782
+ format, validated field by field; a malformed file raises `ValueError`), so it
783
+ is safe on files from others. `PyRuleAnalyzer.load()` on any other path,
784
+ `RuleClassifier.load()` and the `model_pkl` argument use `pickle`, and checking
785
+ a `.cpn` file evaluates the inscriptions written in it: both can run arbitrary
786
+ code. Only load pickles and nets you trust.
787
+
788
+ ## API reference
789
+
790
+ ### PyRuleAnalyzer
791
+
792
+ The high-level entry point; it wraps a `RuleClassifier` and is a scikit-learn
793
+ classifier (`fit`, `predict`, `predict_proba`, `score`, `classes_`,
794
+ `get_params`/`set_params`), so `clone`, `Pipeline`, `cross_val_score` and
795
+ `GridSearchCV` work with `new_model(...)`:
796
+
797
+ ```python
798
+ from sklearn.model_selection import GridSearchCV
799
+
800
+ search = GridSearchCV(PyRuleAnalyzer.new_model("Decision Tree", {"random_state": 0}),
801
+ param_grid={"max_depth": [2, 3, 4]}, cv=5).fit(X_train, y_train)
802
+ ```
803
+
804
+ The parameters are `model` and the hyperparameters of the scikit-learn
805
+ estimator. `fit` trains and extracts the rules; refinement is a separate step
806
+ (`execute_rule_refinement`), not part of a search or a cross-validation.
807
+
808
+ **Labels.** Any labels scikit-learn accepts work. Integer labels (`0, 1, 2,
809
+ ...` or any integers) are used as they are. Other labels (`"cat"`/`"dog"`, or
810
+ labels given as `class_names`) are encoded: the rules and every engine work on
811
+ their codes `0..K-1` (their position in `classes_`), and the classifier keeps
812
+ the table (`classifier.label_table`). `predict`, `classes_`, `score`,
813
+ `compare_initial_final_results` and the `.py` export answer the original
814
+ labels; the C header, the Arduino sketch and the `.bin` model answer the codes
815
+ (the C and Arduino files list the table in a comment, the `.bin` and JSON files
816
+ store it). The CPN and the model checker work on the codes too.
817
+
818
+ **Missing values.** A decision tree or forest (also ExtraTrees) routes a
819
+ missing value (NaN) as scikit-learn does: each split sends it to the side
820
+ recorded in `tree_.missing_go_to_left` (learned when the tree was fitted on
821
+ data with NaN; otherwise the child that received more training samples). The
822
+ rules record that side per condition, and every engine and export follows it:
823
+ `predict`, `predict_proba`, single samples, the `.py`, `.bin`, JSON, C header
824
+ and Arduino exports. Refinement keeps it consistent (a merged split takes its
825
+ routing with it). `GradientBoostingClassifier` refuses NaN, and so does a
826
+ model extracted from it. The CPN models real-valued inputs: the net and its
827
+ evaluator refuse a NaN sample instead of answering it differently. Rules that
828
+ do not record the routing (read from text, an older JSON or `.bin` file, an
829
+ added condition) refuse NaN as before.
830
+
831
+ | Method | Description |
832
+ |---|---|
833
+ | `PyRuleAnalyzer.new_model(model, params=None)` | An untrained analyzer: `"Decision Tree"`, `"Random Forest"` or `"Gradient Boosting Decision Trees"` |
834
+ | `.fit(X, y)` | Train the scikit-learn model and extract its rules |
835
+ | `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` |
836
+ | `PyRuleAnalyzer.create(train_path, test_path, model, params, refine)` | Same, from CSV files |
837
+ | `.execute_rule_refinement(X, y, remove_below_n_classifications=-1, refine_between_trees=False, ...)` | Refine; returns `rules_before`, `rules_after`, `rules_removed`, `reduction_percent` |
838
+ | `.compare_initial_final_results(X, y)` | Metrics and disagreements, initial against refined |
839
+ | `.predict(X, use_refined=True)`, `.predict_proba(X, ...)` | Vectorised prediction |
840
+ | `.summary_report()` | A dict: model type, total rules, classes and every rule |
841
+ | `.to_python(path)`, `.to_binary(path)`, `.to_c_header(path)` | Standalone exports |
842
+ | `.export(base_name, formats, use_refined)` | Several formats at once, under `files/` |
843
+ | `.export_hcpn(base_name, which, sample)` | Write `<base>_initial.cpn` / `<base>_final.cpn` |
844
+ | `.model_check(which, samples, test_samples, reduction, askctl, ...)` | Export if needed and verify; `"both"` also compares |
845
+ | `.edit_rules()` | Edit the rules by hand |
846
+ | `.save_json(path)`, `PyRuleAnalyzer.load_json(path)` | Save/load as JSON -- safe on untrusted files, keeps the rules |
847
+ | `.save(path)`, `PyRuleAnalyzer.load(path)` | JSON when `path` ends in `.json`, else pickle (trusted files only) |
848
+ | `PyRuleAnalyzer.load_binary(path)` | Load a `.bin` export (predicts; no rules) |
849
+
850
+ ### RuleClassifier (`.classifier`)
851
+
852
+ | Method | Description |
853
+ |---|---|
854
+ | `classify(sample, final=False)` | One sample (dict); returns `(class, votes, probabilities)` |
855
+ | `predict_batch(X, feature_names=None, use_final=None)` | Vectorised classes; `use_final` picks the refined or initial set |
856
+ | `predict_batch_proba(X, feature_names=None, use_final=None)` | Vectorised probabilities |
857
+ | `compile_tree_arrays(rules=None, feature_names=None)` | Compile the rules into flat arrays; raises if the rules of a tree are not a partition |
858
+ | `export_to_arduino_ino(filepath, board_model='auto', serial_baud=115200)` | A full sketch, with a memory check |
859
+ | `to_cpn_tools(filepath, use_final=None, sample=None)` | The HCPN of the classifier |
860
+ | `find_duplicated_rules()`, `merge_boundary_redundancy()` | The refinement building blocks |
861
+ | `calculate_structural_complexity(rules, n_features_total)` | The Structural Complexity Score of a rule set |
862
+ | `set_custom_rule_removal(func)`, `adjust_and_remove_rules(method)` | Custom refinement |
863
+ | `to_json(path)`, `RuleClassifier.from_json(path)` (`to_dict()`/`from_dict()`) | Save/load as JSON (safe) |
864
+ | `RuleClassifier.load(path)`, `RuleClassifier.load_binary(path)` | Load a pickle (trusted files only) or a `.bin` |
865
+
866
+ ### Rule
867
+
868
+ One decision path. Uses `__slots__`.
869
+
870
+ | Attribute | Description |
871
+ |---|---|
872
+ | `name` | Unique id, e.g. `Rule3_Class1`, `DT0_Rule2_Class1` (RF), `GBDT1T2_Rule0_Class1` (GBDT) |
873
+ | `class_` | Predicted class |
874
+ | `conditions`, `parsed_conditions` | The conditions as text and as `(feature, op, threshold)` tuples |
875
+ | `usage_count`, `error_count` | Refinement samples that reached the rule, and how many of them it got wrong |
876
+ | `class_distribution` | (RF) the leaf's class counts |
877
+ | `leaf_value`, `learning_rate`, `contribution`, `class_group` | (GBDT) raw leaf value, rate, `learning_rate * leaf_value`, and the class channel |
878
+
879
+ ### Analyzers
880
+
881
+ `DTAnalyzer`, `RFAnalyzer` and `GBDTAnalyzer` are the per-algorithm wrappers
882
+ `execute_rule_refinement()` dispatches to. Each exposes
883
+ `execute_rule_refinement()` and `compare_initial_final_results()`, with a
884
+ breakdown of the redundancy found (intra-tree, inter-tree, low impact, low
885
+ usage).
886
+
887
+ ### Verification
888
+
889
+ | Object | Purpose |
890
+ |---|---|
891
+ | `check_cpn(path, samples=None, classifier=None, class_labels=None, ...)` | Verify an existing `.cpn` in one call |
892
+ | `CPNModelChecker(path)` | The checker: `.check()`, `.export_askctl()` |
893
+ | `ModelCheckResult` | `.passed`, `.failures`, `.properties`, `.report()`, `.to_dict()`, `.latex_table()` |
894
+ | `compare_results(initial, final)` | Side by side, flagging every regression |
895
+ | `PROPERTY_CATALOG` | The property descriptors: id, name, formula, kind, families |
896
+ | `CPNToolsOracle()` / `compare_with_oracle(path)` | Run CPN Tools 4.0.1 headlessly and compare |
897
+ | `make_mutants(path, out_dir)` | One mutant per property, for sensitivity checks |
898
+ | `verified_pipeline(...)`, `VerificationError` | The whole flow, and its gate |
899
+
900
+ ## Project layout
901
+
902
+ ```
903
+ pyruleanalyzer/
904
+ ├── pyruleanalyzer/
905
+ │ ├── pyruleanalyzer.py # PyRuleAnalyzer: the high-level entry point
906
+ │ ├── rule_classifier.py # RuleClassifier: the engine, combining the mixins below
907
+ │ ├── _rules.py # Rule and Condition (imported from rule_classifier)
908
+ │ ├── _labels.py # label codes, input checks (NaN, features)
909
+ │ ├── _engine.py # iterative single-sample engine (classify)
910
+ │ ├── _native_python.py # generated Python: in-memory function, .py export
911
+ │ ├── _arrays.py # compiled tree arrays, predict_batch / predict_batch_proba
912
+ │ ├── _binary_format.py # .bin export and loading
913
+ │ ├── _c_export.py # C header (.h) and Arduino sketch (.ino) export
914
+ │ ├── _refinement.py # redundancy analysis and rule refinement
915
+ │ ├── _serialization.py # pickle loading, JSON format
916
+ │ ├── _reporting.py # reports, metrics, comparisons, rule editing
917
+ │ ├── _extraction.py # data loading, rule extraction from scikit-learn
918
+ │ ├── exporters.py # to_python / to_c_header / to_binary / to_cpn_tools
919
+ │ ├── dt_analyzer.py rf_analyzer.py gbdt_analyzer.py
920
+ │ ├── _accel.py _tree_traversal.c # C extension and numpy fallback
921
+ │ ├── cpn_tools_exporter.py # HCPN export (.cpn)
922
+ │ ├── cpn_profile.py # the tree profile, a CPNCheck plugin
923
+ │ ├── model_checker.py cpn_semantics.py cpn_statespace.py
924
+ │ ├── cpntools_oracle.py cpn_mutants.py
925
+ │ ├── full_pipeline.py # data -> Arduino sketch
926
+ │ └── verified_pipeline.py # train -> verify -> refine -> verify -> deploy
927
+ ├── tests/ # invariants (DT/RF/GBDT), rule fidelity, CPN export, model checker
928
+ ├── examples/ # end-to-end scripts, benchmarks, Arduino tests, CPNCheck walkthrough
929
+ ├── docs/ # Sphinx site and docs/figures (the figures of this page)
930
+ ├── pyproject.toml setup.py
931
+ └── CHANGELOG.md
932
+ ```
933
+
934
+ **Files produced.** `.pkl` (scikit-learn and rule-classifier models),
935
+ `output_*.txt` reports, `.py`, `.bin`, `.h`, `.ino`, `.cpn` (one per stage) and
936
+ `.sml` (ASK-CTL query scripts for CPN Tools).
937
+
938
+ ## Tests
939
+
940
+ ```bash
941
+ pytest tests/ # everything
942
+ pytest tests/test_rule_fidelity.py # every engine against the reference (~20 s; uses gcc if present)
943
+ pytest tests/test_cpn_export.py tests/test_model_checker.py # after touching the exporter or refinement
944
+ ```
945
+
946
+ Three invariants are checked on 25 configurations of each model type: the
947
+ initial rules reproduce scikit-learn; boundary merging alone never changes a
948
+ prediction; and degradation is monotonic as the low-usage threshold grows.
949
+
950
+ ## Documentation
951
+
952
+ The full documentation, with tutorials, is at
953
+ **https://grupocybersegurancavirtus.github.io/pyruleanalyzer/**. To build it
954
+ locally:
955
+
956
+ ```bash
957
+ pip install -e .[docs]
958
+ cd docs && make html
959
+ ```
960
+
961
+ ## Status
962
+
963
+ Version 2.1.0; [CHANGELOG.md](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/CHANGELOG.md)
964
+ says what changed. The figures on this page are drawn from real runs by
965
+ [`docs/figures/make_figures.py`](https://github.com/GrupoCybersegurancaVirtus/pyruleanalyzer/blob/main/docs/figures/make_figures.py).
966
+
967
+ MIT licensed. Developed by
968
+ [GrupoCybersegurancaVirtus](https://github.com/GrupoCybersegurancaVirtus).