raretree 0.14.1rc4__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.1rc4/CHANGELOG.md +13 -0
- raretree-0.14.1rc4/LICENSE +21 -0
- raretree-0.14.1rc4/MANIFEST.in +4 -0
- raretree-0.14.1rc4/PKG-INFO +79 -0
- raretree-0.14.1rc4/README.md +51 -0
- raretree-0.14.1rc4/docs/RELEASE_PRIVACY.md +23 -0
- raretree-0.14.1rc4/examples/v011_demo.py +31 -0
- raretree-0.14.1rc4/examples/v012_classic.py +19 -0
- raretree-0.14.1rc4/examples/v013_temporal_selection.py +27 -0
- raretree-0.14.1rc4/examples/v014_interpretability.py +37 -0
- raretree-0.14.1rc4/pyproject.toml +34 -0
- raretree-0.14.1rc4/setup.cfg +4 -0
- raretree-0.14.1rc4/src/raretree/__init__.py +49 -0
- raretree-0.14.1rc4/src/raretree/ensemble.py +218 -0
- raretree-0.14.1rc4/src/raretree/evaluation.py +49 -0
- raretree-0.14.1rc4/src/raretree/interpretability.py +315 -0
- raretree-0.14.1rc4/src/raretree/monotonic.py +136 -0
- raretree-0.14.1rc4/src/raretree/rare_objectives.py +36 -0
- raretree-0.14.1rc4/src/raretree/stability.py +99 -0
- raretree-0.14.1rc4/src/raretree/temporal_selection.py +212 -0
- raretree-0.14.1rc4/src/raretree/temporal_validation.py +49 -0
- raretree-0.14.1rc4/src/raretree/tree.py +633 -0
- raretree-0.14.1rc4/src/raretree.egg-info/PKG-INFO +79 -0
- raretree-0.14.1rc4/src/raretree.egg-info/SOURCES.txt +42 -0
- raretree-0.14.1rc4/src/raretree.egg-info/dependency_links.txt +1 -0
- raretree-0.14.1rc4/src/raretree.egg-info/requires.txt +9 -0
- raretree-0.14.1rc4/src/raretree.egg-info/top_level.txt +1 -0
- raretree-0.14.1rc4/tests/test_business_constraints.py +78 -0
- raretree-0.14.1rc4/tests/test_business_contract_v031.py +102 -0
- raretree-0.14.1rc4/tests/test_public_synthetic.py +30 -0
- raretree-0.14.1rc4/tests/test_quality_v07.py +71 -0
- raretree-0.14.1rc4/tests/test_sql_parity_v06.py +36 -0
- raretree-0.14.1rc4/tests/test_tree.py +43 -0
- raretree-0.14.1rc4/tests/test_v010_ensemble.py +200 -0
- raretree-0.14.1rc4/tests/test_v011_monotonic_stability.py +204 -0
- raretree-0.14.1rc4/tests/test_v012_classic_defaults.py +102 -0
- raretree-0.14.1rc4/tests/test_v013_temporal_selection.py +195 -0
- raretree-0.14.1rc4/tests/test_v014_interpretability.py +237 -0
- raretree-0.14.1rc4/tests/test_v02.py +60 -0
- raretree-0.14.1rc4/tests/test_v04.py +58 -0
- raretree-0.14.1rc4/tests/test_v05.py +29 -0
- raretree-0.14.1rc4/tests/test_v06.py +157 -0
- raretree-0.14.1rc4/tests/test_v08.py +128 -0
- raretree-0.14.1rc4/tests/test_v09.py +148 -0
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## Unreleased — privacy-reviewed candidate
|
|
4
|
+
|
|
5
|
+
- Generic decision-tree code and optional modules preserved.
|
|
6
|
+
- Replaced sector-specific example data with independently authored abstract
|
|
7
|
+
synthetic benchmark fixtures, not intended to model any real organization.
|
|
8
|
+
- Excluded historical performance results and legacy baseline snapshots that
|
|
9
|
+
cannot be reproduced with the new generator.
|
|
10
|
+
- Added provenance and Git-history publication safeguards.
|
|
11
|
+
- Includes earlier fixes for writable temporal masks and Wilson CI boundaries.
|
|
12
|
+
|
|
13
|
+
No benchmark superiority or production suitability is claimed.
|
|
@@ -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.
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: raretree
|
|
3
|
+
Version: 0.14.1rc4
|
|
4
|
+
Summary: Interpretable decision trees with optional rare-event business 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
|
+
**Experimental, interpretable decision trees with opt-in rare-event constraints.**
|
|
32
|
+
|
|
33
|
+
Pure Python/NumPy classifier. The default is a classic Gini tree; optional
|
|
34
|
+
constraints, rare-event objectives, temporal validation and interpretability
|
|
35
|
+
are explicitly enabled by users. No claim of superiority over scikit-learn.
|
|
36
|
+
|
|
37
|
+
## Installation and tests
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
python -m pip install -e ".[dev]"
|
|
41
|
+
python -m pytest -q
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Quickstart (invented data)
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
import numpy as np
|
|
48
|
+
from raretree import RareTreeClassifier, explain_predictions
|
|
49
|
+
|
|
50
|
+
X = np.array([[0.1], [0.2], [0.9], [1.1], [1.2], [1.3]])
|
|
51
|
+
y = np.array([0, 0, 0, 1, 1, 1])
|
|
52
|
+
model = RareTreeClassifier().fit(X, y)
|
|
53
|
+
print(model.predict(X))
|
|
54
|
+
print(explain_predictions(model, X[:2]))
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Optional features include `max_depth`, `max_conditions`, `min_samples_leaf`,
|
|
58
|
+
`min_positive_leaf`, `level_order`, `no_repeat`, grouped categorical splits,
|
|
59
|
+
bagging, rare-event objectives, monotonicity, temporal selection, per-leaf auditing
|
|
60
|
+
and exports to JSON, DOT and SQL. SQL has not been validated on a live BigQuery
|
|
61
|
+
environment. Leaf frequencies are not calibrated probabilities.
|
|
62
|
+
|
|
63
|
+
## Synthetic benchmarks
|
|
64
|
+
|
|
65
|
+
`benchmarks/synthetic_data.py` generates invented, unitless input features
|
|
66
|
+
and artificial event labels. Old benchmark result files have been removed:
|
|
67
|
+
metrics from the superseded generator cannot be used to characterize this
|
|
68
|
+
candidate. Run new benchmarks before making quality claims.
|
|
69
|
+
|
|
70
|
+
## Publication gate
|
|
71
|
+
|
|
72
|
+
See [docs/RELEASE_PRIVACY.md](docs/RELEASE_PRIVACY.md). This is a sanitized
|
|
73
|
+
**private candidate**, not a public release. The original repository's Git
|
|
74
|
+
history still contains superseded content. Do not make the original repository
|
|
75
|
+
public. Create a new repository with fresh history after code-ownership review.
|
|
76
|
+
|
|
77
|
+
## License
|
|
78
|
+
|
|
79
|
+
MIT License, Copyright (c) 2026 Renato Frazão. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# rareTree
|
|
2
|
+
|
|
3
|
+
**Experimental, interpretable decision trees with opt-in rare-event constraints.**
|
|
4
|
+
|
|
5
|
+
Pure Python/NumPy classifier. The default is a classic Gini tree; optional
|
|
6
|
+
constraints, rare-event objectives, temporal validation and interpretability
|
|
7
|
+
are explicitly enabled by users. No claim of superiority over scikit-learn.
|
|
8
|
+
|
|
9
|
+
## Installation and tests
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
python -m pip install -e ".[dev]"
|
|
13
|
+
python -m pytest -q
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Quickstart (invented data)
|
|
17
|
+
|
|
18
|
+
```python
|
|
19
|
+
import numpy as np
|
|
20
|
+
from raretree import RareTreeClassifier, explain_predictions
|
|
21
|
+
|
|
22
|
+
X = np.array([[0.1], [0.2], [0.9], [1.1], [1.2], [1.3]])
|
|
23
|
+
y = np.array([0, 0, 0, 1, 1, 1])
|
|
24
|
+
model = RareTreeClassifier().fit(X, y)
|
|
25
|
+
print(model.predict(X))
|
|
26
|
+
print(explain_predictions(model, X[:2]))
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Optional features include `max_depth`, `max_conditions`, `min_samples_leaf`,
|
|
30
|
+
`min_positive_leaf`, `level_order`, `no_repeat`, grouped categorical splits,
|
|
31
|
+
bagging, rare-event objectives, monotonicity, temporal selection, per-leaf auditing
|
|
32
|
+
and exports to JSON, DOT and SQL. SQL has not been validated on a live BigQuery
|
|
33
|
+
environment. Leaf frequencies are not calibrated probabilities.
|
|
34
|
+
|
|
35
|
+
## Synthetic benchmarks
|
|
36
|
+
|
|
37
|
+
`benchmarks/synthetic_data.py` generates invented, unitless input features
|
|
38
|
+
and artificial event labels. Old benchmark result files have been removed:
|
|
39
|
+
metrics from the superseded generator cannot be used to characterize this
|
|
40
|
+
candidate. Run new benchmarks before making quality claims.
|
|
41
|
+
|
|
42
|
+
## Publication gate
|
|
43
|
+
|
|
44
|
+
See [docs/RELEASE_PRIVACY.md](docs/RELEASE_PRIVACY.md). This is a sanitized
|
|
45
|
+
**private candidate**, not a public release. The original repository's Git
|
|
46
|
+
history still contains superseded content. Do not make the original repository
|
|
47
|
+
public. Create a new repository with fresh history after code-ownership review.
|
|
48
|
+
|
|
49
|
+
## License
|
|
50
|
+
|
|
51
|
+
MIT License, Copyright (c) 2026 Renato Frazão. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Privacy and provenance gate before public distribution
|
|
2
|
+
|
|
3
|
+
This candidate contains generic decision-tree code and entirely artificial
|
|
4
|
+
unitless demonstration inputs. The new benchmark generator uses identifiers
|
|
5
|
+
such as A1, B2 and variable names such as `medida_1`. These are independent
|
|
6
|
+
synthetic definitions, not approximations of any employer's operational data,
|
|
7
|
+
scoring rules, procedures, or measured event rates.
|
|
8
|
+
|
|
9
|
+
Historical quality reports, archived results, and obsolete version baselines
|
|
10
|
+
are intentionally excluded: old results do not apply to the new fixture.
|
|
11
|
+
Do not quote those old numbers as claims about this candidate.
|
|
12
|
+
|
|
13
|
+
**Git history:** This branch has an ancestor commit with superseded content.
|
|
14
|
+
A sanitized branch or merge does NOT erase ancestors, existing pull requests,
|
|
15
|
+
cached diffs, copies, or artifacts. The original repository must stay private.
|
|
16
|
+
Before publishing, initialize a fresh repository with a new root commit based
|
|
17
|
+
only on this reviewed snapshot. Do not automatically force-push or delete
|
|
18
|
+
private history.
|
|
19
|
+
|
|
20
|
+
**Legal:** An absence of names or data is not proof of ownership. Manually
|
|
21
|
+
verify all source-code rights, relevant employment agreements and third-party
|
|
22
|
+
attributions before distributing under MIT. No automated scan can certify that
|
|
23
|
+
source code is independent of confidential or employer-owned material.
|
|
@@ -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.1rc4"
|
|
8
|
+
authors = [{name = "Renato Frazão"}]
|
|
9
|
+
description = "Interpretable decision trees with optional rare-event business 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()))
|