raretree 0.14.1__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.
- raretree-0.14.1/CHANGELOG.md +24 -0
- raretree-0.14.1/LICENSE +21 -0
- raretree-0.14.1/MANIFEST.in +4 -0
- raretree-0.14.1/PKG-INFO +101 -0
- raretree-0.14.1/README.md +73 -0
- raretree-0.14.1/docs/RELEASE_PRIVACY.md +19 -0
- raretree-0.14.1/examples/v011_demo.py +31 -0
- raretree-0.14.1/examples/v012_classic.py +19 -0
- raretree-0.14.1/examples/v013_temporal_selection.py +27 -0
- raretree-0.14.1/examples/v014_interpretability.py +37 -0
- raretree-0.14.1/pyproject.toml +34 -0
- raretree-0.14.1/setup.cfg +4 -0
- raretree-0.14.1/src/raretree/__init__.py +49 -0
- raretree-0.14.1/src/raretree/ensemble.py +218 -0
- raretree-0.14.1/src/raretree/evaluation.py +49 -0
- raretree-0.14.1/src/raretree/interpretability.py +315 -0
- raretree-0.14.1/src/raretree/monotonic.py +136 -0
- raretree-0.14.1/src/raretree/rare_objectives.py +36 -0
- raretree-0.14.1/src/raretree/stability.py +99 -0
- raretree-0.14.1/src/raretree/temporal_selection.py +212 -0
- raretree-0.14.1/src/raretree/temporal_validation.py +49 -0
- raretree-0.14.1/src/raretree/tree.py +633 -0
- raretree-0.14.1/src/raretree.egg-info/PKG-INFO +101 -0
- raretree-0.14.1/src/raretree.egg-info/SOURCES.txt +42 -0
- raretree-0.14.1/src/raretree.egg-info/dependency_links.txt +1 -0
- raretree-0.14.1/src/raretree.egg-info/requires.txt +9 -0
- raretree-0.14.1/src/raretree.egg-info/top_level.txt +1 -0
- raretree-0.14.1/tests/test_business_constraints.py +78 -0
- raretree-0.14.1/tests/test_business_contract_v031.py +102 -0
- raretree-0.14.1/tests/test_public_synthetic.py +30 -0
- raretree-0.14.1/tests/test_quality_v07.py +71 -0
- raretree-0.14.1/tests/test_sql_parity_v06.py +36 -0
- raretree-0.14.1/tests/test_tree.py +43 -0
- raretree-0.14.1/tests/test_v010_ensemble.py +200 -0
- raretree-0.14.1/tests/test_v011_monotonic_stability.py +204 -0
- raretree-0.14.1/tests/test_v012_classic_defaults.py +102 -0
- raretree-0.14.1/tests/test_v013_temporal_selection.py +195 -0
- raretree-0.14.1/tests/test_v014_interpretability.py +237 -0
- raretree-0.14.1/tests/test_v02.py +60 -0
- raretree-0.14.1/tests/test_v04.py +58 -0
- raretree-0.14.1/tests/test_v05.py +29 -0
- raretree-0.14.1/tests/test_v06.py +157 -0
- raretree-0.14.1/tests/test_v08.py +128 -0
- raretree-0.14.1/tests/test_v09.py +148 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.14.1 — Stable package version
|
|
4
|
+
|
|
5
|
+
- First version without a prerelease suffix, enabling normal installation with
|
|
6
|
+
`pip install raretree`.
|
|
7
|
+
- Updated public README, installation examples, release metadata and provenance
|
|
8
|
+
documentation.
|
|
9
|
+
- No changes to the decision-tree training or prediction implementation
|
|
10
|
+
relative to the tested `0.14.1rc4` candidate.
|
|
11
|
+
- Experimental optional features retain their documented limitations;
|
|
12
|
+
this release is not a certification of production suitability.
|
|
13
|
+
|
|
14
|
+
## 0.14.1rc4 — Release candidate
|
|
15
|
+
|
|
16
|
+
- Preserved generic decision-tree code and opt-in modules.
|
|
17
|
+
- Replaced sector-oriented examples with abstract, independently generated
|
|
18
|
+
synthetic benchmark inputs.
|
|
19
|
+
- Excluded obsolete benchmark result files and superseded performance
|
|
20
|
+
snapshots that cannot be reproduced using the current generator.
|
|
21
|
+
- Included fixes for writable temporal masks and Wilson confidence interval
|
|
22
|
+
boundaries.
|
|
23
|
+
|
|
24
|
+
No benchmark superiority or production suitability is claimed.
|
raretree-0.14.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Renato Frazão
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
raretree-0.14.1/PKG-INFO
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: raretree
|
|
3
|
+
Version: 0.14.1
|
|
4
|
+
Summary: Interpretable decision trees with optional rare-event constraints
|
|
5
|
+
Author: Renato Frazão
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Keywords: decision-tree,machine-learning,explainability,rare-events
|
|
8
|
+
Classifier: Development Status :: 4 - Beta
|
|
9
|
+
Classifier: Intended Audience :: Science/Research
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: numpy>=1.24
|
|
21
|
+
Provides-Extra: temporal
|
|
22
|
+
Requires-Dist: pandas>=1.5; extra == "temporal"
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
25
|
+
Requires-Dist: scikit-learn>=1.3; extra == "dev"
|
|
26
|
+
Requires-Dist: pandas>=1.5; extra == "dev"
|
|
27
|
+
Dynamic: license-file
|
|
28
|
+
|
|
29
|
+
# rareTree
|
|
30
|
+
|
|
31
|
+
Interpretable decision trees for binary classification, with optional tools for
|
|
32
|
+
rare events, model auditing and temporal evaluation.
|
|
33
|
+
|
|
34
|
+
The default `RareTreeClassifier` uses a classic Gini decision tree. Advanced
|
|
35
|
+
constraints and objectives are **opt-in**: they are not applied unless selected.
|
|
36
|
+
|
|
37
|
+
## Installation
|
|
38
|
+
|
|
39
|
+
Requires Python 3.10 or newer.
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
python -m pip install raretree
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
For optional temporal features using pandas:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
python -m pip install "raretree[temporal]"
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Quickstart
|
|
52
|
+
|
|
53
|
+
The following example uses only invented, dimensionless values.
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
import numpy as np
|
|
57
|
+
from raretree import RareTreeClassifier
|
|
58
|
+
|
|
59
|
+
X = np.array([[1.0], [2.0], [3.0], [8.0], [9.0], [10.0]])
|
|
60
|
+
y = np.array([0, 0, 0, 1, 1, 1])
|
|
61
|
+
|
|
62
|
+
model = RareTreeClassifier().fit(X, y)
|
|
63
|
+
print(model.predict(X)) # [0 0 0 1 1 1]
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Optional capabilities
|
|
67
|
+
|
|
68
|
+
- Tree structure controls such as `max_depth`, `min_samples_leaf` and
|
|
69
|
+
`max_conditions`.
|
|
70
|
+
- Optional constraints and objective functions for rare events.
|
|
71
|
+
- Bagging, monotonicity constraints and grouped categorical splits.
|
|
72
|
+
- Temporal validation, model selection and stability assessment.
|
|
73
|
+
- Prediction explanations, leaf auditing, and exports to JSON, DOT and SQL.
|
|
74
|
+
|
|
75
|
+
These features are opt-in; the basic classifier does not require them.
|
|
76
|
+
|
|
77
|
+
## Important limitations
|
|
78
|
+
|
|
79
|
+
- This is the first **non-prerelease package version** (`0.14.1`); that does
|
|
80
|
+
not imply certification for production or safety-critical decisions.
|
|
81
|
+
- Leaf event frequencies must not be treated as calibrated probabilities.
|
|
82
|
+
- SQL exports have not been validated against a live BigQuery environment.
|
|
83
|
+
- No superiority over scikit-learn is claimed. Validate accuracy, runtime,
|
|
84
|
+
stability and suitability on your own datasets before deployment.
|
|
85
|
+
|
|
86
|
+
## Synthetic benchmarks and development
|
|
87
|
+
|
|
88
|
+
`benchmarks/synthetic_data.py` generates invented, unitless inputs and
|
|
89
|
+
artificial labels. Historical benchmark reports from older fixtures are not
|
|
90
|
+
applicable to the current generator.
|
|
91
|
+
|
|
92
|
+
To run the test suite from a source checkout:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
python -m pip install -e ".[dev]"
|
|
96
|
+
python -m pytest -q
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## License
|
|
100
|
+
|
|
101
|
+
MIT License. Copyright (c) 2026 Renato Frazão.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# rareTree
|
|
2
|
+
|
|
3
|
+
Interpretable decision trees for binary classification, with optional tools for
|
|
4
|
+
rare events, model auditing and temporal evaluation.
|
|
5
|
+
|
|
6
|
+
The default `RareTreeClassifier` uses a classic Gini decision tree. Advanced
|
|
7
|
+
constraints and objectives are **opt-in**: they are not applied unless selected.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
Requires Python 3.10 or newer.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
python -m pip install raretree
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
For optional temporal features using pandas:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
python -m pip install "raretree[temporal]"
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Quickstart
|
|
24
|
+
|
|
25
|
+
The following example uses only invented, dimensionless values.
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
import numpy as np
|
|
29
|
+
from raretree import RareTreeClassifier
|
|
30
|
+
|
|
31
|
+
X = np.array([[1.0], [2.0], [3.0], [8.0], [9.0], [10.0]])
|
|
32
|
+
y = np.array([0, 0, 0, 1, 1, 1])
|
|
33
|
+
|
|
34
|
+
model = RareTreeClassifier().fit(X, y)
|
|
35
|
+
print(model.predict(X)) # [0 0 0 1 1 1]
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Optional capabilities
|
|
39
|
+
|
|
40
|
+
- Tree structure controls such as `max_depth`, `min_samples_leaf` and
|
|
41
|
+
`max_conditions`.
|
|
42
|
+
- Optional constraints and objective functions for rare events.
|
|
43
|
+
- Bagging, monotonicity constraints and grouped categorical splits.
|
|
44
|
+
- Temporal validation, model selection and stability assessment.
|
|
45
|
+
- Prediction explanations, leaf auditing, and exports to JSON, DOT and SQL.
|
|
46
|
+
|
|
47
|
+
These features are opt-in; the basic classifier does not require them.
|
|
48
|
+
|
|
49
|
+
## Important limitations
|
|
50
|
+
|
|
51
|
+
- This is the first **non-prerelease package version** (`0.14.1`); that does
|
|
52
|
+
not imply certification for production or safety-critical decisions.
|
|
53
|
+
- Leaf event frequencies must not be treated as calibrated probabilities.
|
|
54
|
+
- SQL exports have not been validated against a live BigQuery environment.
|
|
55
|
+
- No superiority over scikit-learn is claimed. Validate accuracy, runtime,
|
|
56
|
+
stability and suitability on your own datasets before deployment.
|
|
57
|
+
|
|
58
|
+
## Synthetic benchmarks and development
|
|
59
|
+
|
|
60
|
+
`benchmarks/synthetic_data.py` generates invented, unitless inputs and
|
|
61
|
+
artificial labels. Historical benchmark reports from older fixtures are not
|
|
62
|
+
applicable to the current generator.
|
|
63
|
+
|
|
64
|
+
To run the test suite from a source checkout:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
python -m pip install -e ".[dev]"
|
|
68
|
+
python -m pytest -q
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## License
|
|
72
|
+
|
|
73
|
+
MIT License. Copyright (c) 2026 Renato Frazão.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Data and release verification
|
|
2
|
+
|
|
3
|
+
This distribution contains generic decision-tree code, unitless demonstration
|
|
4
|
+
inputs and synthetic benchmark examples. The synthetic generator creates
|
|
5
|
+
artificial labels and neutral feature names; it is not intended to represent
|
|
6
|
+
any real organization's observations, procedures or event rates.
|
|
7
|
+
|
|
8
|
+
Historical benchmark summaries based on earlier fixtures have been excluded.
|
|
9
|
+
Do not use their numbers to characterize the package. Assess model quality
|
|
10
|
+
with independently reproducible experiments and datasets appropriate to the
|
|
11
|
+
intended application.
|
|
12
|
+
|
|
13
|
+
The project is distributed under the MIT license. Automated scans for
|
|
14
|
+
identifiers or sensitive data cannot establish legal ownership or replace
|
|
15
|
+
review of source-code rights and third-party notices.
|
|
16
|
+
|
|
17
|
+
Before publishing any future version, review source files, distribution
|
|
18
|
+
archives, documentation and dependency changes. A successful CI build is not
|
|
19
|
+
a guarantee that a model is suitable for production.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
"""Purely synthetic example: classic tree, monotonic tree and temporal audit.
|
|
2
|
+
Run with: python examples/v011_demo.py (requires pandas).
|
|
3
|
+
"""
|
|
4
|
+
import numpy as np
|
|
5
|
+
import pandas as pd
|
|
6
|
+
from raretree import RareTreeClassifier, MonotonicRareTreeClassifier, temporal_stability_report
|
|
7
|
+
|
|
8
|
+
rng=np.random.default_rng(202611)
|
|
9
|
+
n=9000
|
|
10
|
+
X=pd.DataFrame({'medida_1':rng.integers(0,30,n),
|
|
11
|
+
'historico_abstrato':rng.integers(0,10,n),
|
|
12
|
+
'valor_abstrato':rng.uniform(200,3000,n)})
|
|
13
|
+
logit=-7.0+0.15*X['medida_1']-0.16*X['historico_abstrato']+0.00008*X['valor_abstrato']
|
|
14
|
+
y=rng.binomial(1,1/(1+np.exp(-logit)))
|
|
15
|
+
|
|
16
|
+
# Deliberately disjoint synthetic train and future validation cohorts.
|
|
17
|
+
train=slice(0,6000)
|
|
18
|
+
valid=slice(6000,9000)
|
|
19
|
+
params=dict(criterion='gini',max_depth=5,min_samples_leaf=50,min_positive_leaf=2)
|
|
20
|
+
classic=RareTreeClassifier(**params).fit(X.iloc[train],y[train])
|
|
21
|
+
constrained=MonotonicRareTreeClassifier(
|
|
22
|
+
monotonic_constraints={'medida_1':1,'historico_abstrato':-1},**params
|
|
23
|
+
).fit(X.iloc[train],y[train])
|
|
24
|
+
print('Classic leaves:',classic.n_leaves_,'Monotonic leaves:',constrained.n_leaves_)
|
|
25
|
+
print('Classic and constrained trees have same rules:',classic.export_sql()==constrained.export_sql())
|
|
26
|
+
print('Changes to predicted rates:',constrained.monotonic_adjustments_)
|
|
27
|
+
validation_dates=['2026-01-15']*1000+['2026-02-15']*1000+['2026-03-15']*1000
|
|
28
|
+
report=temporal_stability_report(constrained,X.iloc[valid],y[valid],
|
|
29
|
+
validation_dates,training_end='2025-12-31')
|
|
30
|
+
print('Temporal summary:',report['summary'])
|
|
31
|
+
print('Example SQL probability:',constrained.export_probability_sql()[:220],'...')
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"""Runnable classic and business-constraint example using synthetic data."""
|
|
2
|
+
import numpy as np
|
|
3
|
+
from raretree import RareTreeClassifier
|
|
4
|
+
|
|
5
|
+
rng = np.random.default_rng(12012)
|
|
6
|
+
X_train = rng.normal(size=(2000, 5))
|
|
7
|
+
probability = 1 / (1 + np.exp(-(-3 + 1.2 * X_train[:, 0] - 0.7 * X_train[:, 1])))
|
|
8
|
+
y_train = rng.binomial(1, probability)
|
|
9
|
+
|
|
10
|
+
classic = RareTreeClassifier().fit(X_train, y_train)
|
|
11
|
+
business = RareTreeClassifier(
|
|
12
|
+
max_depth=8, min_samples_leaf=50,
|
|
13
|
+
min_positive_leaf=5, max_conditions=5,
|
|
14
|
+
max_candidates=255, no_repeat=True,
|
|
15
|
+
).fit(X_train, y_train)
|
|
16
|
+
|
|
17
|
+
print('Classic tree leaves:', classic.n_leaves_)
|
|
18
|
+
print('Restricted tree leaves:', business.n_leaves_)
|
|
19
|
+
print('Example probabilities:', business.predict_proba(X_train[:3])[:, 1])
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""Minimal walk-forward selection; purely fictitious numeric toy data."""
|
|
2
|
+
import numpy as np
|
|
3
|
+
import pandas as pd
|
|
4
|
+
from raretree import RareTreeClassifier, select_temporal_model
|
|
5
|
+
|
|
6
|
+
rng = np.random.default_rng(2026)
|
|
7
|
+
frames = []
|
|
8
|
+
for i, date in enumerate(['2024-01-01', '2024-04-01', '2024-07-01', '2024-10-01']):
|
|
9
|
+
x = rng.normal(size=500)
|
|
10
|
+
p = 1/(1+np.exp(-(-3 + 1.5*x)))
|
|
11
|
+
frames.append(pd.DataFrame({'date': date, 'id': [f'{i}-{j}' for j in range(500)],
|
|
12
|
+
'x': x, 'event': rng.binomial(1, p)}))
|
|
13
|
+
history = pd.concat(frames, ignore_index=True)
|
|
14
|
+
configs = {
|
|
15
|
+
'shallow': lambda: RareTreeClassifier(max_depth=2, min_samples_leaf=20),
|
|
16
|
+
'deep': lambda: RareTreeClassifier(max_depth=5, min_samples_leaf=20),
|
|
17
|
+
}
|
|
18
|
+
selection = select_temporal_model(
|
|
19
|
+
configs, history, features=['x'], target_column='event', date_column='date',
|
|
20
|
+
entity_column='id', periods=[('2024-04-01','2024-07-01'),
|
|
21
|
+
('2024-07-01','2024-10-01'),
|
|
22
|
+
('2024-10-01','2025-01-01')],
|
|
23
|
+
objective='recall_at_k', top_fraction=0.05, stability_penalty=0.5)
|
|
24
|
+
print('Chosen candidate from past validation:', selection['best_name'])
|
|
25
|
+
print('Validation-only leaderboard:', selection['leaderboard'])
|
|
26
|
+
model = configs[selection['best_name']]().fit(history[['x']], history['event'])
|
|
27
|
+
print('Refitted for future prediction, without using any future labels:', model.n_leaves_)
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""v0.14 demonstration with SYNTHETIC data only; no corporate records."""
|
|
2
|
+
import json
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
|
|
5
|
+
import numpy as np
|
|
6
|
+
|
|
7
|
+
from raretree import (
|
|
8
|
+
RareTreeClassifier, explain_predictions, export_tree_json,
|
|
9
|
+
export_tree_dot, audit_leaf_coverage,
|
|
10
|
+
)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def main():
|
|
14
|
+
rng = np.random.default_rng(1400)
|
|
15
|
+
X = rng.normal(size=(700, 3))
|
|
16
|
+
risk = 1.4 * (X[:, 0] > 0.4) + 1.2 * (X[:, 1] < -0.5) - 3
|
|
17
|
+
p = 1 / (1 + np.exp(-risk))
|
|
18
|
+
y = (rng.random(len(X)) < p).astype(int)
|
|
19
|
+
train_x, hold_x = X[:500], X[500:]
|
|
20
|
+
model = RareTreeClassifier(max_depth=3, min_samples_leaf=25).fit(train_x, y[:500])
|
|
21
|
+
# Labels in holdout are used only in audit, never fitting or tuning.
|
|
22
|
+
reports = {
|
|
23
|
+
'explanations': explain_predictions(model, hold_x[:3]),
|
|
24
|
+
'tree': export_tree_json(model),
|
|
25
|
+
'audit': audit_leaf_coverage(model, hold_x, y[500:]),
|
|
26
|
+
}
|
|
27
|
+
out = Path(__file__).parent / 'out_v014'
|
|
28
|
+
out.mkdir(parents=True, exist_ok=True)
|
|
29
|
+
(out / 'demonstracao_sintetica.json').write_text(json.dumps(reports, indent=2, ensure_ascii=False))
|
|
30
|
+
(out / 'arvore_sintetica.dot').write_text(export_tree_dot(model), encoding='utf-8')
|
|
31
|
+
print('Arquivos sintéticos:', out)
|
|
32
|
+
print('Amostras explicadas:', reports['explanations']['explained_rows'])
|
|
33
|
+
print('PSI folhas:', round(reports['audit']['population_stability_index'], 4))
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
if __name__ == '__main__':
|
|
37
|
+
main()
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "raretree"
|
|
7
|
+
version = "0.14.1"
|
|
8
|
+
authors = [{name = "Renato Frazão"}]
|
|
9
|
+
description = "Interpretable decision trees with optional rare-event constraints"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
keywords = ["decision-tree", "machine-learning", "explainability", "rare-events"]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Development Status :: 4 - Beta",
|
|
15
|
+
"Intended Audience :: Science/Research",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Programming Language :: Python :: 3.10",
|
|
19
|
+
"Programming Language :: Python :: 3.11",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
readme = "README.md"
|
|
26
|
+
requires-python = ">=3.10"
|
|
27
|
+
dependencies = ["numpy>=1.24"]
|
|
28
|
+
|
|
29
|
+
[project.optional-dependencies]
|
|
30
|
+
temporal = ["pandas>=1.5"]
|
|
31
|
+
dev = ["pytest>=7", "scikit-learn>=1.3", "pandas>=1.5"]
|
|
32
|
+
|
|
33
|
+
[tool.setuptools.packages.find]
|
|
34
|
+
where = ["src"]
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
from .tree import RareTreeClassifier
|
|
2
|
+
|
|
3
|
+
__all__ = ["RareTreeClassifier"]
|
|
4
|
+
from .temporal_validation import purged_walk_forward_splits
|
|
5
|
+
|
|
6
|
+
__all__.append("purged_walk_forward_splits")
|
|
7
|
+
|
|
8
|
+
# Separate opt-in wrapper; no RareTreeClassifier fit/predict path changes.
|
|
9
|
+
from .ensemble import BaggedRareTreeClassifier
|
|
10
|
+
|
|
11
|
+
__all__.append("BaggedRareTreeClassifier")
|
|
12
|
+
|
|
13
|
+
# New v0.11 extensions are opt-in. Classic Gini tree code remains unchanged.
|
|
14
|
+
from .monotonic import MonotonicRareTreeClassifier
|
|
15
|
+
from .stability import temporal_stability_report
|
|
16
|
+
|
|
17
|
+
__all__.extend(['MonotonicRareTreeClassifier', 'temporal_stability_report'])
|
|
18
|
+
|
|
19
|
+
# Lazy optional temporal model selection: no changes to RareTreeClassifier.fit.
|
|
20
|
+
def select_temporal_model(*args, **kwargs):
|
|
21
|
+
from .temporal_selection import select_temporal_model as _select
|
|
22
|
+
return _select(*args, **kwargs)
|
|
23
|
+
|
|
24
|
+
def binary_ranking_metrics(*args, **kwargs):
|
|
25
|
+
from .temporal_selection import binary_ranking_metrics as _metrics
|
|
26
|
+
return _metrics(*args, **kwargs)
|
|
27
|
+
|
|
28
|
+
__all__.extend(["select_temporal_model", "binary_ranking_metrics"])
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
# v0.14: ALL interpretability tools are lazy and opt-in. No cost to tree.fit().
|
|
32
|
+
def explain_predictions(*args, **kwargs):
|
|
33
|
+
from .interpretability import explain_predictions as _fn
|
|
34
|
+
return _fn(*args, **kwargs)
|
|
35
|
+
|
|
36
|
+
def export_tree_json(*args, **kwargs):
|
|
37
|
+
from .interpretability import export_tree_json as _fn
|
|
38
|
+
return _fn(*args, **kwargs)
|
|
39
|
+
|
|
40
|
+
def export_tree_dot(*args, **kwargs):
|
|
41
|
+
from .interpretability import export_tree_dot as _fn
|
|
42
|
+
return _fn(*args, **kwargs)
|
|
43
|
+
|
|
44
|
+
def audit_leaf_coverage(*args, **kwargs):
|
|
45
|
+
from .interpretability import audit_leaf_coverage as _fn
|
|
46
|
+
return _fn(*args, **kwargs)
|
|
47
|
+
|
|
48
|
+
__all__.extend(['explain_predictions', 'export_tree_json',
|
|
49
|
+
'export_tree_dot', 'audit_leaf_coverage'])
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
"""Opt-in bagging for RareTree. Never invoked by RareTreeClassifier itself.
|
|
2
|
+
|
|
3
|
+
Only NumPy is required. Every constituent tree is an ordinary
|
|
4
|
+
RareTreeClassifier, including all its optional business constraints.
|
|
5
|
+
"""
|
|
6
|
+
from collections.abc import Mapping
|
|
7
|
+
import numpy as np
|
|
8
|
+
|
|
9
|
+
from .tree import RareTreeClassifier
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class BaggedRareTreeClassifier:
|
|
13
|
+
"""Bootstrap ensemble of unchanged RareTreeClassifier instances.
|
|
14
|
+
|
|
15
|
+
Parameters
|
|
16
|
+
----------
|
|
17
|
+
n_estimators : int, default=9
|
|
18
|
+
Number of independent tree fits. Only the ensemble incurs this cost.
|
|
19
|
+
max_samples : float or int, default=1.0
|
|
20
|
+
Fraction in (0,1] of rows per tree, or integer number of rows.
|
|
21
|
+
bootstrap : bool, default=True
|
|
22
|
+
Sample with replacement if True, otherwise without replacement.
|
|
23
|
+
stratified : bool, default=True
|
|
24
|
+
Draw within each training label class. This protects rare-event
|
|
25
|
+
representation *within training*, never sampling the holdout.
|
|
26
|
+
Extremely small classes may be upsampled if bootstrap=True.
|
|
27
|
+
random_state : int or None, default=42
|
|
28
|
+
Reproducible local random generator; does not modify global state.
|
|
29
|
+
tree_params : mapping or None
|
|
30
|
+
Passed verbatim to each standard RareTreeClassifier, including
|
|
31
|
+
min_positive_leaf, level_order, no_repeat and criterion.
|
|
32
|
+
|
|
33
|
+
Predictions average constituent positive-class scores. These are not
|
|
34
|
+
calibrated probabilities. `predict_score_std` describes disagreement,
|
|
35
|
+
not a confidence interval or an uncertainty guarantee.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
def __init__(self, n_estimators=9, max_samples=1.0, bootstrap=True,
|
|
39
|
+
stratified=True, random_state=42, tree_params=None):
|
|
40
|
+
self.n_estimators = n_estimators
|
|
41
|
+
self.max_samples = max_samples
|
|
42
|
+
self.bootstrap = bootstrap
|
|
43
|
+
self.stratified = stratified
|
|
44
|
+
self.random_state = random_state
|
|
45
|
+
self.tree_params = tree_params
|
|
46
|
+
|
|
47
|
+
def _validate_parameters(self, n):
|
|
48
|
+
if (isinstance(self.n_estimators, (bool, np.bool_)) or
|
|
49
|
+
not isinstance(self.n_estimators, (int, np.integer)) or
|
|
50
|
+
self.n_estimators < 1):
|
|
51
|
+
raise ValueError('n_estimators must be a positive integer')
|
|
52
|
+
if not isinstance(self.bootstrap, (bool, np.bool_)):
|
|
53
|
+
raise ValueError('bootstrap must be boolean')
|
|
54
|
+
if not isinstance(self.stratified, (bool, np.bool_)):
|
|
55
|
+
raise ValueError('stratified must be boolean')
|
|
56
|
+
if (self.random_state is not None and
|
|
57
|
+
(isinstance(self.random_state, (bool, np.bool_)) or
|
|
58
|
+
not isinstance(self.random_state, (int, np.integer)) or
|
|
59
|
+
self.random_state < 0)):
|
|
60
|
+
raise ValueError('random_state must be None or a nonnegative integer')
|
|
61
|
+
if self.tree_params is not None and not isinstance(self.tree_params, Mapping):
|
|
62
|
+
raise ValueError('tree_params must be a mapping or None')
|
|
63
|
+
if isinstance(self.max_samples, (bool, np.bool_)):
|
|
64
|
+
raise ValueError('max_samples cannot be boolean')
|
|
65
|
+
if isinstance(self.max_samples, (int, np.integer)):
|
|
66
|
+
m = int(self.max_samples)
|
|
67
|
+
if not 1 <= m <= n:
|
|
68
|
+
raise ValueError('integer max_samples must be within 1..n_samples')
|
|
69
|
+
elif isinstance(self.max_samples, (float, np.floating)):
|
|
70
|
+
if not np.isfinite(self.max_samples) or not 0 < self.max_samples <= 1:
|
|
71
|
+
raise ValueError('fractional max_samples must be within (0, 1]')
|
|
72
|
+
m = max(1, int(round(n * float(self.max_samples))))
|
|
73
|
+
else:
|
|
74
|
+
raise ValueError('max_samples must be an integer count or float fraction')
|
|
75
|
+
return m
|
|
76
|
+
|
|
77
|
+
@staticmethod
|
|
78
|
+
def _take_rows(X, indices):
|
|
79
|
+
if hasattr(X, 'iloc'):
|
|
80
|
+
return X.iloc[indices]
|
|
81
|
+
return np.asarray(X)[indices]
|
|
82
|
+
|
|
83
|
+
@staticmethod
|
|
84
|
+
def _stratified_indices(y, m, replace, rng):
|
|
85
|
+
"""Proportional training-only draws, at least one of each observed class.
|
|
86
|
+
|
|
87
|
+
For subsampling without replacement, cap group draws by group size.
|
|
88
|
+
"""
|
|
89
|
+
classes, counts = np.unique(y, return_counts=True)
|
|
90
|
+
if m < len(classes):
|
|
91
|
+
raise ValueError('max_samples must allow at least one row per class when stratified')
|
|
92
|
+
desired = m * counts.astype(float) / len(y)
|
|
93
|
+
allocations = np.floor(desired).astype(int)
|
|
94
|
+
allocations = np.maximum(allocations, 1)
|
|
95
|
+
if not replace:
|
|
96
|
+
allocations = np.minimum(allocations, counts)
|
|
97
|
+
# Largest remainder with deterministic tie breaking; enforce min one.
|
|
98
|
+
while allocations.sum() < m:
|
|
99
|
+
eligible = (allocations < counts) if not replace else np.ones(len(classes), dtype=bool)
|
|
100
|
+
index = np.argmax(np.where(eligible, desired - allocations, -np.inf))
|
|
101
|
+
allocations[index] += 1
|
|
102
|
+
while allocations.sum() > m:
|
|
103
|
+
eligible = allocations > 1
|
|
104
|
+
index = np.argmax(np.where(eligible, allocations - desired, -np.inf))
|
|
105
|
+
allocations[index] -= 1
|
|
106
|
+
portions = []
|
|
107
|
+
for cls, size in zip(classes, allocations):
|
|
108
|
+
group = np.flatnonzero(y == cls)
|
|
109
|
+
portions.append(rng.choice(group, size=int(size), replace=replace))
|
|
110
|
+
indices = np.concatenate(portions)
|
|
111
|
+
rng.shuffle(indices)
|
|
112
|
+
return indices
|
|
113
|
+
|
|
114
|
+
@staticmethod
|
|
115
|
+
def _extend_categories_from_training(X, tree):
|
|
116
|
+
"""Recognize categories present in full training, not only a bootstrap.
|
|
117
|
+
|
|
118
|
+
Appending categories preserves every original trained category code and
|
|
119
|
+
thus the fitted tree's split logic. This is only needed for the strict
|
|
120
|
+
unknown-category error policy. Truly novel test categories still error.
|
|
121
|
+
Never inspect holdout/prediction data when building this vocabulary.
|
|
122
|
+
"""
|
|
123
|
+
if tree.unknown_category != 'error' or not tree._categorical:
|
|
124
|
+
return
|
|
125
|
+
for col_index in tree._categorical:
|
|
126
|
+
if hasattr(X, 'iloc'):
|
|
127
|
+
values = list(X.iloc[:, col_index].dropna().unique())
|
|
128
|
+
else:
|
|
129
|
+
values = []
|
|
130
|
+
for value in np.asarray(X)[:, col_index]:
|
|
131
|
+
if not tree._missing_scalar(value) and value not in values:
|
|
132
|
+
values.append(value)
|
|
133
|
+
existing = tree._categories[col_index]
|
|
134
|
+
for value in values:
|
|
135
|
+
if value not in existing:
|
|
136
|
+
existing.append(value)
|
|
137
|
+
|
|
138
|
+
def fit(self, X, y):
|
|
139
|
+
y = np.asarray(y)
|
|
140
|
+
if y.ndim != 1 or y.size == 0 or not np.isin(y, [0, 1]).all():
|
|
141
|
+
raise ValueError('y must be a nonempty binary one-dimensional array')
|
|
142
|
+
if not hasattr(X, 'shape') or len(X.shape) != 2 or len(X) != len(y):
|
|
143
|
+
raise ValueError('X must be a 2D matrix aligned with y')
|
|
144
|
+
m = self._validate_parameters(len(y))
|
|
145
|
+
params = {} if self.tree_params is None else dict(self.tree_params)
|
|
146
|
+
rng = np.random.default_rng(self.random_state)
|
|
147
|
+
# Train into a local list, committing only after success.
|
|
148
|
+
estimators = []
|
|
149
|
+
for _ in range(int(self.n_estimators)):
|
|
150
|
+
if self.stratified:
|
|
151
|
+
indices = self._stratified_indices(y, m, self.bootstrap, rng)
|
|
152
|
+
else:
|
|
153
|
+
indices = rng.choice(len(y), size=m, replace=self.bootstrap)
|
|
154
|
+
tree = RareTreeClassifier(**params)
|
|
155
|
+
tree.fit(self._take_rows(X, indices), y[indices])
|
|
156
|
+
self._extend_categories_from_training(X, tree)
|
|
157
|
+
estimators.append(tree)
|
|
158
|
+
self.estimators_ = estimators
|
|
159
|
+
self.classes_ = np.array([0, 1])
|
|
160
|
+
self.feature_names_in_ = list(estimators[0].feature_names_in_)
|
|
161
|
+
self.n_features_in_ = estimators[0].n_features_in_
|
|
162
|
+
self.base_rate_ = float(y.mean())
|
|
163
|
+
self.n_samples_per_estimator_ = m
|
|
164
|
+
return self
|
|
165
|
+
|
|
166
|
+
def _check_fitted(self):
|
|
167
|
+
if not hasattr(self, 'estimators_'):
|
|
168
|
+
raise RuntimeError('Call fit before prediction')
|
|
169
|
+
|
|
170
|
+
def predict_proba(self, X):
|
|
171
|
+
self._check_fitted()
|
|
172
|
+
# Streaming accumulation: O(n_predictions) workspace, independent
|
|
173
|
+
# of number of trees. Unlike stacking, does not allocate n x n_trees.
|
|
174
|
+
p = None
|
|
175
|
+
for tree in self.estimators_:
|
|
176
|
+
current = tree.predict_proba(X)[:, 1]
|
|
177
|
+
if p is None:
|
|
178
|
+
p = current.copy()
|
|
179
|
+
else:
|
|
180
|
+
p += current
|
|
181
|
+
p /= len(self.estimators_)
|
|
182
|
+
return np.column_stack((1 - p, p))
|
|
183
|
+
|
|
184
|
+
def predict(self, X):
|
|
185
|
+
return (self.predict_proba(X)[:, 1] >= 0.5).astype(np.int8)
|
|
186
|
+
|
|
187
|
+
def predict_score_std(self, X):
|
|
188
|
+
"""Per-row std. dev. between tree scores (NOT a calibrated CI)."""
|
|
189
|
+
self._check_fitted()
|
|
190
|
+
mean = None
|
|
191
|
+
m2 = None
|
|
192
|
+
for k, tree in enumerate(self.estimators_, start=1):
|
|
193
|
+
scores = tree.predict_proba(X)[:, 1]
|
|
194
|
+
if mean is None:
|
|
195
|
+
mean = scores.copy()
|
|
196
|
+
m2 = np.zeros_like(scores)
|
|
197
|
+
else:
|
|
198
|
+
delta = scores - mean
|
|
199
|
+
mean += delta / k
|
|
200
|
+
m2 += delta * (scores - mean)
|
|
201
|
+
return np.sqrt(np.maximum(m2 / len(self.estimators_), 0.0))
|
|
202
|
+
|
|
203
|
+
def feature_usage_frequency(self):
|
|
204
|
+
"""Fraction of fitted trees where each feature appears in a split."""
|
|
205
|
+
self._check_fitted()
|
|
206
|
+
used_counts = np.zeros(self.n_features_in_, dtype=int)
|
|
207
|
+
for model in self.estimators_:
|
|
208
|
+
used = set()
|
|
209
|
+
def visit(node):
|
|
210
|
+
if node.feature is not None:
|
|
211
|
+
used.add(node.feature)
|
|
212
|
+
visit(node.left)
|
|
213
|
+
visit(node.right)
|
|
214
|
+
visit(model.root_)
|
|
215
|
+
for j in used:
|
|
216
|
+
used_counts[j] += 1
|
|
217
|
+
return dict(zip(self.feature_names_in_,
|
|
218
|
+
(used_counts / len(self.estimators_)).tolist()))
|