Metadata-Version: 2.3
Name: elo-grad
Version: 0.2.2
Summary: Add your description here
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: numpy>=2.1.2
Requires-Dist: pandas>=2.2.3
Requires-Dist: scikit-learn>=1.5.2
Provides-Extra: examples
Requires-Dist: ipykernel>=6.29.5; extra == 'examples'
Requires-Dist: matplotlib>=3.9.2; extra == 'examples'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.9.2; extra == 'plot'
Description-Content-Type: text/markdown

# :chess_pawn: EloGrad

**Extended Elo model implementation.**

**EloGrad** leverages the framing of the 
[Elo rating system](https://en.wikipedia.org/wiki/Elo_rating_system)
as logistic regression with stochastic gradient descent
(see [this blog](https://stmorse.github.io/journal/Elo.html) for a nice walkthrough)
to offer a collection of extensions to the rating system.
All models are `scikit-learn` compatible.

## :book: Installation

You can install `elo-grad` with:
```bash
pip install elo-grad
```

## :stopwatch: Quick Start

Detailed example notebooks are provided in the `examples/` directory.
To install any extra dependencies required to run the notebooks install with:
```bash
pip install elo-grad[examples]
```

### :clipboard: Minimal Example

```python
from elo_grad import EloEstimator

# Input DataFrame with sorted index of Unix timestamps
# and columns entity_1 | entity_2 | score
# where score = 1 if player_1 won and score = 0 if
# player_2 won.
df = ...
estimator = EloEstimator(
    k_factor=20, 
    default_init_rating=1200,
    entity_cols=("player_1", "player_2"),
    score_col="result",
)
# Get expected scores
expected_scores = estimator.predict_proba(df)
# Get final ratings (of form (Unix timestamp, rating))
ratings = estimator.model.ratings
```

## :compass: Roadmap

In rough order, things we want to add are:
- Proper documentation
- Support for additional features, e.g. home advantage
- Regularization (L1 & L2)
- Support for Polars
- Head-to-head ratings
- Other optimizers, e.g. momentum
- Poisson model support
- Support for draws
- Extend plotting support, e.g. plotly

## :blue_book: References

1. Elo rating system: https://en.wikipedia.org/wiki/Elo_rating_system
2. Elo rating system as logistic regression with stochastic gradient descent: https://stmorse.github.io/journal/Elo.html
