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.
- pyruleanalyzer-2.1.0/PKG-INFO +968 -0
- pyruleanalyzer-2.1.0/README.md +926 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyproject.toml +11 -7
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/__init__.py +12 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_accel.py +347 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_arrays.py +965 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_binary_format.py +567 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_c_export.py +724 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_engine.py +439 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_extraction.py +833 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_labels.py +393 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_native_python.py +459 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_pycodegen.py +119 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_refinement.py +1249 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_reporting.py +526 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_rules.py +478 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/_serialization.py +519 -0
- pyruleanalyzer-2.1.0/pyruleanalyzer/compositional.py +1441 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpn_mutants.py +33 -9
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpn_profile.py +7 -12
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpn_semantics.py +206 -4
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpn_tools_exporter.py +56 -3
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/dt_analyzer.py +25 -10
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/exporters.py +9 -9
- pyruleanalyzer-2.1.0/pyruleanalyzer/footprint.py +608 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/full_pipeline.py +207 -121
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/gbdt_analyzer.py +190 -13
- pyruleanalyzer-2.1.0/pyruleanalyzer/model_checker.py +527 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/pyruleanalyzer.py +614 -103
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/rf_analyzer.py +22 -8
- pyruleanalyzer-2.1.0/pyruleanalyzer/rule_classifier.py +329 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/verified_pipeline.py +150 -26
- pyruleanalyzer-2.1.0/pyruleanalyzer.egg-info/PKG-INFO +968 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer.egg-info/SOURCES.txt +28 -2
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer.egg-info/requires.txt +4 -4
- pyruleanalyzer-2.1.0/tests/test_cheap_fixes.py +325 -0
- pyruleanalyzer-2.1.0/tests/test_compositional.py +219 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_coverage_and_precision.py +29 -2
- pyruleanalyzer-2.1.0/tests/test_cpn_safe_eval.py +290 -0
- pyruleanalyzer-2.1.0/tests/test_engine_hardening.py +447 -0
- pyruleanalyzer-2.1.0/tests/test_footprint.py +195 -0
- pyruleanalyzer-2.1.0/tests/test_full_pipeline.py +196 -0
- pyruleanalyzer-2.1.0/tests/test_json_serialization.py +481 -0
- pyruleanalyzer-2.1.0/tests/test_labels_and_nan.py +652 -0
- pyruleanalyzer-2.1.0/tests/test_refinement_v2.py +267 -0
- pyruleanalyzer-2.1.0/tests/test_regressions.py +286 -0
- pyruleanalyzer-2.1.0/tests/test_sklearn_api.py +184 -0
- pyruleanalyzer-2.1.0/tests/test_usage_engine.py +83 -0
- pyruleanalyzer-2.1.0/tests/test_verified_pipeline_gate.py +187 -0
- pyruleanalyzer-2.0.0/PKG-INFO +0 -1110
- pyruleanalyzer-2.0.0/README.md +0 -1069
- pyruleanalyzer-2.0.0/pyruleanalyzer/_accel.py +0 -176
- pyruleanalyzer-2.0.0/pyruleanalyzer/model_checker.py +0 -224
- pyruleanalyzer-2.0.0/pyruleanalyzer/parsers.py +0 -272
- pyruleanalyzer-2.0.0/pyruleanalyzer/rule_classifier.py +0 -5338
- pyruleanalyzer-2.0.0/pyruleanalyzer.egg-info/PKG-INFO +0 -1110
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/LICENSE +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/_tree_traversal.c +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpn_statespace.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer/cpntools_oracle.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer.egg-info/dependency_links.txt +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer.egg-info/entry_points.txt +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/pyruleanalyzer.egg-info/top_level.txt +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/setup.cfg +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/setup.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_export.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile_counterexamples.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile_generic.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile_oracle.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile_reduction.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_cpn_profile_structural.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_dt_invariants.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_gbdt_invariants.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_model_checker.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_predict_batch.py +0 -0
- {pyruleanalyzer-2.0.0 → pyruleanalyzer-2.1.0}/tests/test_rf_invariants.py +0 -0
- {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
|
+
[](https://www.python.org/downloads/)
|
|
46
|
+
[](https://opensource.org/licenses/MIT)
|
|
47
|
+
[](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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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).
|