elo-grad 0.2.0

Add your description here

:chess_pawn: EloGrad

Extended Elo model implementation.

EloGrad leverages the framing of the Elo rating system as logistic regression with stochastic gradient descent (see this blog 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:

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:

pip install elo-grad[examples]

:clipboard: Minimal Example

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