Metadata-Version: 2.4
Name: bisection-regressor
Version: 0.2.0
Summary: A scikit-learn-compatible regressor that predicts continuous targets via a cascade of binary classifiers bisecting the target's value range.
Author: Vihan
Project-URL: Homepage, https://github.com/vihan015/bisection-regressor
Project-URL: Documentation, https://github.com/vihan015/bisection-regressor/tree/main/docs
Project-URL: Repository, https://github.com/vihan015/bisection-regressor
Project-URL: Bug Tracker, https://github.com/vihan015/bisection-regressor/issues
Keywords: machine-learning,regression,scikit-learn,decision-tree
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scikit-learn>=1.2
Requires-Dist: joblib>=1.2
Provides-Extra: benchmarks
Requires-Dist: pandas>=1.5; extra == "benchmarks"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# BisectionRegressor

A scikit-learn-compatible regressor that predicts continuous targets by
recursively bisecting the target's value range, using a binary
classifier at each node to decide which half a sample falls into.
Predictions are formed by softly blending both branches at every node,
weighted by the classifier's confidence (via the law of total
expectation), rather than committing to a single hard path.

Works as a drop-in scikit-learn estimator: `Pipeline`, `GridSearchCV`,
`cross_val_score`, `clone`, `sample_weight` are all supported.

## Install

From PyPI:

```bash
pip install bisection-regressor
```

From source, for development:

```bash
git clone https://github.com/vihan015/bisection-regressor.git
cd bisection-regressor
pip install -e .
```

To also run the benchmarks (needs `pandas`):

```bash
pip install -e ".[benchmarks]"
```

## Quick start

```python
from sklearn.datasets import load_diabetes
from sklearn.model_selection import train_test_split
from bisection_regressor import BisectionRegressor

X, y = load_diabetes(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.25, random_state=0)

reg = BisectionRegressor(max_depth=6)
reg.fit(X_train, y_train)
print(reg.score(X_test, y_test))   # R^2
```

## Documentation

- [`docs/hyperparameters.md`](docs/hyperparameters.md): every
  hyperparameter explained, plus usage examples covering `Pipeline`,
  `GridSearchCV` (including `BisectionForestRegressor`'s nested
  params), cross-validation, sample weights, and tree inspection.
- [`docs/math_deepdive.md`](docs/math_deepdive.md): a from-scratch
  walkthrough of exactly what `fit()` and `predict()` compute
  internally, and every mathematical concept involved (medians,
  entropy, the law of total expectation, empirical Bayes shrinkage,
  probability calibration, bagging), with a fully worked, verified
  numeric example.

## Results

See [`paper/report.md`](paper/report.md) for the full write-up: how the
method was diagnosed and improved from an initial naive design, the
mathematical justification for each fix, and 5-fold cross-validated
results on three real UCI datasets (Wine Quality, Concrete Compressive
Strength, Auto MPG) against standard baselines (Linear Regression,
Random Forest, Gradient Boosting, and so on), reported honestly,
including where the method does not win.

Reproduce the benchmark yourself: see [`benchmarks/`](benchmarks/).

## Status

This is a research/experimental estimator, not a production-hardened
replacement for gradient boosting or random forests. It's a specific,
interpretable structural alternative. See `paper/report.md` for exactly
where it's competitive and where it isn't.

## License

MIT. See [`LICENSE`](LICENSE).
