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