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.
Files changed (44) hide show
  1. raretree-0.14.1/CHANGELOG.md +24 -0
  2. raretree-0.14.1/LICENSE +21 -0
  3. raretree-0.14.1/MANIFEST.in +4 -0
  4. raretree-0.14.1/PKG-INFO +101 -0
  5. raretree-0.14.1/README.md +73 -0
  6. raretree-0.14.1/docs/RELEASE_PRIVACY.md +19 -0
  7. raretree-0.14.1/examples/v011_demo.py +31 -0
  8. raretree-0.14.1/examples/v012_classic.py +19 -0
  9. raretree-0.14.1/examples/v013_temporal_selection.py +27 -0
  10. raretree-0.14.1/examples/v014_interpretability.py +37 -0
  11. raretree-0.14.1/pyproject.toml +34 -0
  12. raretree-0.14.1/setup.cfg +4 -0
  13. raretree-0.14.1/src/raretree/__init__.py +49 -0
  14. raretree-0.14.1/src/raretree/ensemble.py +218 -0
  15. raretree-0.14.1/src/raretree/evaluation.py +49 -0
  16. raretree-0.14.1/src/raretree/interpretability.py +315 -0
  17. raretree-0.14.1/src/raretree/monotonic.py +136 -0
  18. raretree-0.14.1/src/raretree/rare_objectives.py +36 -0
  19. raretree-0.14.1/src/raretree/stability.py +99 -0
  20. raretree-0.14.1/src/raretree/temporal_selection.py +212 -0
  21. raretree-0.14.1/src/raretree/temporal_validation.py +49 -0
  22. raretree-0.14.1/src/raretree/tree.py +633 -0
  23. raretree-0.14.1/src/raretree.egg-info/PKG-INFO +101 -0
  24. raretree-0.14.1/src/raretree.egg-info/SOURCES.txt +42 -0
  25. raretree-0.14.1/src/raretree.egg-info/dependency_links.txt +1 -0
  26. raretree-0.14.1/src/raretree.egg-info/requires.txt +9 -0
  27. raretree-0.14.1/src/raretree.egg-info/top_level.txt +1 -0
  28. raretree-0.14.1/tests/test_business_constraints.py +78 -0
  29. raretree-0.14.1/tests/test_business_contract_v031.py +102 -0
  30. raretree-0.14.1/tests/test_public_synthetic.py +30 -0
  31. raretree-0.14.1/tests/test_quality_v07.py +71 -0
  32. raretree-0.14.1/tests/test_sql_parity_v06.py +36 -0
  33. raretree-0.14.1/tests/test_tree.py +43 -0
  34. raretree-0.14.1/tests/test_v010_ensemble.py +200 -0
  35. raretree-0.14.1/tests/test_v011_monotonic_stability.py +204 -0
  36. raretree-0.14.1/tests/test_v012_classic_defaults.py +102 -0
  37. raretree-0.14.1/tests/test_v013_temporal_selection.py +195 -0
  38. raretree-0.14.1/tests/test_v014_interpretability.py +237 -0
  39. raretree-0.14.1/tests/test_v02.py +60 -0
  40. raretree-0.14.1/tests/test_v04.py +58 -0
  41. raretree-0.14.1/tests/test_v05.py +29 -0
  42. raretree-0.14.1/tests/test_v06.py +157 -0
  43. raretree-0.14.1/tests/test_v08.py +128 -0
  44. 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.
@@ -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,4 @@
1
+ include LICENSE README.md CHANGELOG.md
2
+ recursive-include docs *.md
3
+ recursive-include examples *.py
4
+ recursive-include tests *.py
@@ -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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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()))