Metadata-Version: 2.4
Name: RuleTree
Version: 2026.10.15.143541
Summary: Interpretable decision trees built node by node with stumps of different kinds, for tabular data, time series and images
Home-page: https://github.com/fismimosa/RuleTree
Author: Cristiano Landi
Author-email: cristiano.landi@phd.unipi.it
License: BSD-Clause-2
Project-URL: Documentation, https://fismimosa.github.io/RuleTree/
Project-URL: Source, https://github.com/fismimosa/RuleTree
Project-URL: Issues, https://github.com/fismimosa/RuleTree/issues
Keywords: decision trees,interpretable machine learning,explainable AI,rules,time series,clustering,scikit-learn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.0
Requires-Dist: scikit-learn>=1.5.0
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: category_encoders
Requires-Dist: psutil
Provides-Extra: shapelets
Requires-Dist: numba; extra == "shapelets"
Provides-Extra: graphviz
Requires-Dist: graphviz; extra == "graphviz"
Requires-Dist: matplotlib; extra == "graphviz"
Provides-Extra: kmedoids
Requires-Dist: scikit-learn-extra; extra == "kmedoids"
Provides-Extra: profiling
Requires-Dist: line-profiler-pycharm; extra == "profiling"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: numba; extra == "test"
Requires-Dist: graphviz; extra == "test"
Requires-Dist: matplotlib; extra == "test"
Provides-Extra: all
Requires-Dist: numba; extra == "all"
Requires-Dist: graphviz; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: scikit-learn-extra; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# RuleTree

RuleTree builds interpretable decision trees one node at a time. Each node is split by a *stump*:
a threshold on a feature or on a combination of a few features (oblique split), the distance from
an instance of the training set (a *pivot*), the distance of a time series from a *shapelet*, which
of two pivots or shapelets is closer, a fair split, ... The same tree can mix different kinds of
stumps and different types of data (tabular data, time series, images), and its rules can be read,
drawn and saved.

- Classification, regression and clustering trees with the scikit-learn API.
- Stumps for tabular data, time series and images, usable together in the same tree.
- Rules as text or Graphviz drawings, feature contributions of each prediction.
- Trees saved to and loaded from JSON, grown further with `partial_fit`.
- Gradient boosting, XGBoost and explainable boosting machines of RuleTrees.
- Metrics to evaluate the models: predictions, clusters, size of the trees and fairness.
- New stumps written by combining a *transformer* (the features) and a *splitter* (the split).

## Installation

RuleTree requires Python 3.10 or later:

```bash
pip install RuleTree                # or, from the root of the repository: pip install .
pip install "RuleTree[shapelets]"   # optional: shapelet, proximity and partial pivot stumps (numba)
pip install "RuleTree[graphviz]"    # optional: drawing the trees (also requires the Graphviz binaries)
pip install "RuleTree[all]"         # all the optional features
```

## Example

```python
from sklearn.datasets import load_iris

from RuleTree import RuleTreeClassifier

X, y = load_iris(return_X_y=True)
model = RuleTreeClassifier(max_depth=2, random_state=0).fit(X, y)
model.print_rules(model.get_rules(columns_names=["sepal length", "sepal width",
                                                  "petal length", "petal width"]))
```

```text
|--- petal width <= 0.8
|    output: 0
|--- petal width > 0.8
|   |--- petal width <= 1.75
|   |    output: 1
|   |--- petal width > 1.75
|   |    output: 2
```

Trees with other stumps and other types of data:

```python
from RuleTree.stumps.classification import DecisionTreeStumpClassifier, ShapeletTreeStumpClassifier

# X: tabular data, X_ts: time series of shape (n_samples, n_signals, length)
model = RuleTreeClassifier(max_depth=3, stump_selection="best",
                           base_stumps=[DecisionTreeStumpClassifier(), ShapeletTreeStumpClassifier()])
model.fit(X=X, X_ts=X_ts, y=y)
```

## Documentation

The user guide is in [`docs/guides`](docs/guides):

- [Getting started](docs/guides/getting_started.rst): classification, regression, clustering.
- [Stumps](docs/guides/stumps.rst): the available stumps and how to combine them.
- [Tabular data, time series and images](docs/guides/multimodal.rst).
- [Reading the tree](docs/guides/inspecting.rst): rules, drawings, nodes, feature contributions.
- [Saving, growing and updating trees](docs/guides/lifecycle.rst).
- [Saving and loading trees](docs/guides/saving.rst): what `to_dict` saves and how `from_dict` rebuilds a tree.
- [Ensembles](docs/guides/ensembles.rst): boosting of RuleTrees.
- [Evaluating the models](docs/guides/evaluating.rst): metrics of predictions, clusters, tree size and fairness.
- [Extending the library](docs/guides/extending.rst): writing new stumps, transformers and splitters.

The HTML documentation, with the API reference, is built with Sphinx:

```bash
pip install -r requirements.txt -r requirements.docs.txt
make -C docs html   # docs/_build/html/index.html
```

More examples are in the notebooks of [`Examples`](Examples).

## Tests

```bash
pip install ".[test]"
pytest
```

The tests include the docstring examples and the code of the guides, whose printed output is
compared with the one in the guides.
