Metadata-Version: 2.4
Name: splinator
Version: 0.3.0
Summary: Python library for fitting linear-spline based logistic regression for calibration.
Author-email: Jiarui Xu <jiarui.xu@affirm.com>
License: BSD-3-Clause
License-File: LICENSE
Keywords: calibration,logistic,regression,spline
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
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
Requires-Python: >=3.9
Requires-Dist: numpy>=1.19.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: scipy>=1.6.0
Provides-Extra: dev
Requires-Dist: jupyter>=1.0.0; extra == 'dev'
Requires-Dist: matplotlib>=3.5.3; extra == 'dev'
Requires-Dist: mypy>=0.971; extra == 'dev'
Requires-Dist: pytest>=7.1.2; extra == 'dev'
Description-Content-Type: text/markdown

# Splinator 📈

**Probablistic Calibration with Regression Splines**

[scikit-learn](https://scikit-learn.org) compatible

[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Documentation Status](https://readthedocs.org/projects/splinator/badge/?version=latest)](https://splinator.readthedocs.io/en/latest/)
[![Build](https://img.shields.io/github/actions/workflow/status/affirm/splinator/.github/workflows/python-package.yml)](https://github.com/affirm/splinator/actions)

## Installation

`pip install splinator`

## Algorithm

Supported models:

- Linear Spline Logistic Regression

Supported metrics:

- Spiegelhalter’s z statistic
- Expected Calibration Error (ECE)

\[1\] You can find more information in the [Linear Spline Logistic
Regression](https://github.com/Affirm/splinator/wiki/Linear-Spline-Logistic-Regression).

\[2\] Additional readings

- Zhang, Jian, and Yiming Yang. [Probabilistic score estimation with
    piecewise logistic
    regression](https://pal.sri.com/wp-content/uploads/publications/radar/2004/icml04zhang.pdf).
    Proceedings of the twenty-first international conference on Machine
    learning. 2004.
- Guo, Chuan, et al. "On calibration of modern neural networks." International conference on machine learning. PMLR, 2017.


## Examples

| comparison                                     | notebook                                                                                                                                                           |
|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| scikit-learn's sigmoid and isotonic regression | [![colab1](https://colab.research.google.com/assets/colab-badge.svg)](https://github.com/Affirm/splinator/blob/main/examples/calibrator_model_comparison.ipynb)    |
| pyGAM’s spline model                           | [![colab2](https://colab.research.google.com/assets/colab-badge.svg)](https://githubtocolab.com/Affirm/splinator/blob/main/examples/spline_model_comparison.ipynb) |

## Development

The dependencies are managed by [uv](https://github.com/astral-sh/uv).

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv sync --dev

# Run tests
uv run pytest tests -v

# Run type checking
uv run mypy src/splinator
```

## Example Usage

``` python
from splinator.estimators import LinearSplineLogisticRegression
import numpy as np

# random synthetic dataset
n_samples = 100
rng = np.random.RandomState(0)
X = rng.normal(loc=100, size=(n_samples, 2))
y = np.random.randint(2, size=n_samples)

lslr = LinearSplineLogisticRegression(n_knots=10)
lslr.fit(X, y)
```
