Competitors

Elo Competitor

class elote.competitors.elo.EloCompetitor(initial_rating: float = 400, k_factor: float | None = None)

Elo rating system competitor.

The Elo rating system is a method for calculating the relative skill levels of players in zero-sum games such as chess. It is named after its creator Arpad Elo, a Hungarian-American physics professor and chess master.

In the Elo system, each player’s rating changes based on the outcome of games and the rating of their opponents. The difference in ratings between two players determines the expected outcome of a match, and the actual outcome is used to update the ratings.

Class Attributes:

_base_rating (float): Base rating divisor used in the transformed rating calculation. Default: 400. _k_factor (float): Factor that determines how much ratings change after each match. Default: 32.

Initialize an Elo competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 400. k_factor (float, optional): The K-factor to use for this competitor. If None,

the class K-factor will be used. Default: None.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating. InvalidParameterException: If the k_factor is negative.

beat(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has won against the given competitor.

This method updates the ratings of both this competitor and the opponent based on the match outcome where this competitor won.

Args:

competitor (BaseCompetitor): The opponent competitor that lost. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Validated but not otherwise used by this rating system.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score against another competitor.

Args:

competitor (BaseCompetitor): The competitor to compare against.

Returns:

float: The expected score (probability of winning).

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

tied(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has tied with the given competitor.

This method updates the ratings of both this competitor and the opponent based on a drawn match outcome.

Args:

competitor (BaseCompetitor): The opponent competitor that tied. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Must be equal. Validated but not otherwise used by this rating system.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

Glicko Competitor

class elote.competitors.glicko.GlickoCompetitor(initial_rating: float = 1500, initial_rd: float = 350, initial_time: datetime | None = None)

Glicko rating system competitor.

The Glicko rating system is an improvement on the Elo rating system that takes into account the reliability of a rating. It was developed by Mark Glickman as an improvement to the Elo system.

In addition to a rating, each competitor has a rating deviation (RD) that measures the reliability of the rating. A higher RD indicates a less reliable rating.

Class Attributes:

_c (float): Rating volatility constant that determines how quickly the RD increases over time.

Default: 34.6, which is calibrated so that it takes about 100 rating periods for a player’s RD to grow from 50 to 350 (maximum uncertainty).

_q (float): Scaling factor used in the rating calculation. Default: 0.0057565. _rating_period_days (float): Number of days that constitute one rating period.

Default: 1.0 (one day per rating period).

Initialize a Glicko competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 1500. initial_rd (float, optional): The initial rating deviation of this competitor. Default: 350. initial_time (datetime, optional): The initial timestamp for this competitor. Default: current time.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating. InvalidParameterException: If the initial RD is not positive.

beat(competitor: GlickoCompetitor, match_time: datetime | None = None, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has won against the given competitor.

This method updates the ratings of both this competitor and the opponent based on the match outcome where this competitor won.

Args:

competitor (GlickoCompetitor): The opponent competitor that lost. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Validated but not otherwise used by this rating system.

match_time (datetime, optional): The time when the match occurred. Default: current time.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score (probability of winning) against another competitor.

Args:

competitor (BaseCompetitor): The opponent competitor to compare against.

Returns:

float: The probability of winning (between 0 and 1).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

tied(competitor: GlickoCompetitor, match_time: datetime | None = None, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has tied with the given competitor.

This method updates the ratings of both this competitor and the opponent based on a drawn match outcome.

Args:

competitor (GlickoCompetitor): The opponent competitor that tied. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Must be equal. Validated but not otherwise used by this rating system.

match_time (datetime, optional): The time when the match occurred. Default: current time.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

Glicko-2 Competitor

class elote.competitors.glicko2.Glicko2Competitor(initial_rating: float = 1500, initial_rd: float = 350, initial_volatility: float | None = None, initial_time: datetime | None = None)

Glicko-2 rating system competitor.

The Glicko-2 rating system is an improvement on the original Glicko system, developed by Mark Glickman. It introduces a volatility parameter that measures the degree of expected fluctuation in a player’s rating.

In Glicko-2, ratings are internally represented in a different scale than displayed to users. The internal scale uses a mean of 0 and a standard deviation of 1, while the displayed scale uses a mean of 1500 and a standard deviation of 173.7.

Class Attributes:

_tau (float): System constant that constrains the volatility over time. Default: 0.5.

Smaller values (e.g., 0.3 to 0.2) make volatility change more slowly. Larger values (e.g., 0.6 to 1.0) allow volatility to change more quickly.

_epsilon (float): Convergence tolerance for the volatility iteration. Default: 0.000001. _default_volatility (float): Default volatility for new competitors. Default: 0.06. _scale_factor (float): Scale factor for converting between Glicko-2 and original scales. Default: 173.7178. _rating_period_days (float): Number of days that constitute one rating period. Default: 1.0.

Initialize a Glicko-2 competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 1500. initial_rd (float, optional): The initial rating deviation of this competitor. Default: 350. initial_volatility (float, optional): The initial volatility of this competitor. Default: _default_volatility. initial_time (datetime, optional): The initial timestamp for this competitor. Default: current time.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating. InvalidParameterException: If the initial RD is not positive or if the initial volatility is not positive.

beat(competitor: BaseCompetitor, match_time: datetime | None = None, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has won against the given competitor.

This method records the match result for later processing during the rating period update. The actual rating update happens when update_ratings() is called.

Args:

competitor (BaseCompetitor): The opponent competitor that lost. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Validated but not otherwise used by this rating system.

match_time (datetime, optional): The time when the match occurred. Default: current time.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match. InvalidParameterException: If the match time is before either competitor’s last activity.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score (probability of winning) against another competitor.

Args:

competitor (BaseCompetitor): The opponent competitor to compare against.

Returns:

float: The probability of winning (between 0 and 1).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

tied(competitor: BaseCompetitor, match_time: datetime | None = None, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has tied with the given competitor.

This method records the match result for later processing during the rating period update. The actual rating update happens when update_ratings() is called.

Args:

competitor (BaseCompetitor): The opponent competitor that tied. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Must be equal. Validated but not otherwise used by this rating system.

match_time (datetime, optional): The time when the match occurred. Default: current time.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match. InvalidParameterException: If the match time is before either competitor’s last activity.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

TrueSkill Competitor

class elote.competitors.trueskill.TrueSkillCompetitor(initial_mu: float = None, initial_sigma: float = None)

TrueSkill rating system competitor.

TrueSkill is a Bayesian skill rating system developed by Microsoft Research. It generalizes the Elo and Glicko rating systems to handle team-based games and multiplayer scenarios. TrueSkill models each player’s skill as a Gaussian distribution with a mean (mu) and standard deviation (sigma).

The mean represents the player’s estimated skill, while the standard deviation represents the system’s uncertainty about that estimate. As more games are played, the uncertainty typically decreases.

Class Attributes:

_beta (float): The skill factor that controls how much the game outcome depends

on skill vs. chance. Default: 4.166.

_tau (float): The additive dynamics factor that increases uncertainty over time.

Default: 0.083.

_draw_probability (float): The probability of a draw. Default: 0.10 (10%). _default_mu (float): The default mean skill value for new players. Default: 25.0. _default_sigma (float): The default standard deviation for new players. Default: 8.333.

Initialize a TrueSkill competitor.

Args:

initial_mu (float, optional): The initial mean skill value. Default: _default_mu. initial_sigma (float, optional): The initial standard deviation. Default: _default_sigma.

Raises:

InvalidParameterException: If the initial sigma is not positive.

beat(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has won against the given competitor.

Args:

competitor (BaseCompetitor): The opponent competitor that lost. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Validated but not otherwise used by this rating system.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score (probability of winning) against another competitor.

Args:

competitor (BaseCompetitor): The opponent competitor to compare against.

Returns:

float: The probability of winning (between 0 and 1).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current conservative rating of this competitor.

TrueSkill uses a conservative rating estimate (mu - 3*sigma) to ensure that a player’s displayed rating has a 99% chance of being below their actual skill level. This encourages players to keep playing to reduce uncertainty and increase their displayed rating.

Returns:

float: The current conservative rating.

tied(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has tied with the given competitor.

Args:

competitor (BaseCompetitor): The opponent competitor that tied. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Must be equal. Validated but not otherwise used by this rating system.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

DWZ Competitor

class elote.competitors.dwz.DWZCompetitor(initial_rating: float = 400)

Deutsche Wertungszahl (DWZ) rating system competitor.

The DWZ is the German chess rating system, similar to Elo but with some differences in how ratings are updated after matches, including factors based on player age and performance.

Class Attributes:

_J (int): Development coefficient. Default: 10.

Initialize a DWZ competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 400.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating.

beat(competitor: BaseCompetitor, age: int | None = None, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor wins against another.

Args:

competitor (BaseCompetitor): The opponent competitor. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Validated but not otherwise used by this rating system.

age (Optional[int]): The age of this competitor at the time of the match.

Used for DWZ calculation. Defaults to 26 (adult).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score (probability of winning) against another competitor.

Args:

competitor (BaseCompetitor): The opponent competitor to compare against.

Returns:

float: The probability of winning (between 0 and 1).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

tied(competitor: BaseCompetitor, age: int | None = None, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor ties with another.

Args:

competitor (BaseCompetitor): The opponent competitor. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Must be equal. Validated but not otherwise used by this rating system.

age (Optional[int]): The age of this competitor at the time of the match.

Used for DWZ calculation. Defaults to 26 (adult).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

ECF Competitor

class elote.competitors.ecf.ECFCompetitor(initial_rating: float = 100)

English Chess Federation (ECF) rating system competitor.

The ECF rating system is used by the English Chess Federation to rate chess players. It uses a moving average of performance ratings over a number of periods.

Class Attributes:

_delta (float): Maximum rating difference considered for updates. Default: 50. _n_periods (int): Number of periods to consider for the moving average. Default: 30.

Initialize an ECF competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 100.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating.

beat(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has won against the given competitor.

This method updates the ratings of both this competitor and the opponent based on the match outcome where this competitor won.

Args:

competitor (BaseCompetitor): The opponent competitor that lost. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Validated but not otherwise used by this rating system.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score (probability of winning) against another competitor.

Args:

competitor (BaseCompetitor): The opponent competitor to compare against.

Returns:

float: The probability of winning (between 0 and 1).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

The rating is the average of all scores in the deque.

Returns:

float: The current rating.

tied(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has tied with the given competitor.

This method updates the ratings of both this competitor and the opponent based on a drawn match outcome.

Args:

competitor (BaseCompetitor): The opponent competitor that tied. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Must be equal. Validated but not otherwise used by this rating system.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

Colley Matrix Competitor

class elote.competitors.colley.ColleyMatrixCompetitor(initial_rating: float | None = None)

Colley Matrix Method competitor.

The Colley Matrix Method is a least-squares rating system that solves a system of linear equations to obtain rankings. Unlike Elo which updates ratings incrementally after each match, Colley Matrix recalculates all ratings using the entire match history.

Key characteristics: - Bias-free (doesn’t depend on schedule order) - Considers only wins and losses (not margin of victory) - Initial rating of 0.5 for all competitors - Final ratings are between 0 and 1 - Sum of all ratings equals n/2 (where n is number of competitors)

Class Attributes:

_minimum_rating (float): The minimum allowed rating value. Default: 0.0 _default_initial_rating (float): Default initial rating for all competitors. Default: 0.5

Initialize a new Colley Matrix competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 0.5.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating.

beat(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has won against the given competitor.

In Colley Matrix Method, we store the match result and recalculate ratings for all related competitors.

Args:

competitor (BaseCompetitor): The opponent competitor that lost. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Validated but not otherwise used by this rating system.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score against another competitor.

Args:

competitor (BaseCompetitor): The competitor to compare against.

Returns:

float: The expected score (probability of winning).

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

This method exports the competitor’s state in a standardized format that can be used to recreate the competitor with the same state.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

tied(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has tied with the given competitor.

Args:

competitor (BaseCompetitor): The opponent competitor that tied. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Must be equal. Validated but not otherwise used by this rating system.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

Massey Competitor

class elote.competitors.massey.MasseyCompetitor(initial_rating: float | None = None)

Massey Ratings competitor.

Massey’s method assigns every competitor a rating such that the difference between two ratings is a least-squares estimate of the margin by which one would beat the other. Like Colley and Bradley-Terry – and unlike Elo – ratings are not nudged after each result; the whole connected group is re-fit from the complete match history, which makes the method order independent.

Margins. beat / lost_to / tied accept the common optional scores payload, the two competitors’ scores in caller order. When it is supplied this is genuine margin-of-victory Massey – the form used in college football rankings – and the margin contributed by a game is self_score - competitor_score. When it is omitted the implementation falls back to unit margins: a win contributes +1 to the winner’s cumulative margin and -1 to the loser’s. A draw contributes 0 either way, while still counting as a game played for both.

Key characteristics: - Global least-squares fit (does not depend on the order of results) - Ratings are zero mean within a connected group, so roughly half of them are negative - The rating difference is directly interpretable as a predicted margin

Class Attributes:

_minimum_rating (float): The minimum allowed rating value. Default: -inf. Massey

ratings are zero mean and routinely negative, so no floor is imposed.

_default_initial_rating (float): Default initial rating. Default: 0.0. _expected_score_scale (float): Logistic scale used by expected_score() to turn a

rating difference into a win probability. Default: 2.0, chosen so that the widest plausible unit-margin gap maps to roughly the same probability as the widest gap under Colley’s 1 / (1 + exp(-4 * diff)).

_round_decimals (int): Number of decimal places fitted ratings are canonicalized to, so

that solver noise cannot make mathematically identical records differ. Default: 13.

Initialize a new Massey competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 0.0.

beat(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has won against the given competitor.

The result is recorded in the match graph and the whole connected group is re-fit.

Args:

competitor (BaseCompetitor): The opponent competitor that lost. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). When supplied, the margin contributed to the Massey system is the real self_score - competitor_score; when omitted the unit margin +1 / -1 is used.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score against another competitor.

Massey ratings are on a margin scale rather than a probability scale, so the predicted margin r_self - r_competitor is squashed through a logistic function to obtain a win probability. Two competitors with equal ratings give exactly 0.5, and the two argument orders are exactly complementary.

Args:

competitor (BaseCompetitor): The competitor to compare against.

Returns:

float: The expected score (probability of winning).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

This method exports the competitor’s state in a standardized format that can be used to recreate the competitor with the same state. The format includes: - type: The class name of the competitor - version: The version of the serialization format - created_at: The timestamp when the state was exported - id: A unique identifier for this state export - parameters: The parameters used to initialize the competitor - state: The current state variables of the competitor

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

tied(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has tied with the given competitor.

A draw contributes nothing to either cumulative margin, but counts as a game played for both competitors.

Args:

competitor (BaseCompetitor): The opponent competitor that tied. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). They must be equal, so a drawn game contributes a zero margin whether or not scores are supplied.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

Keener Competitor

class elote.competitors.keener.KeenerCompetitor(initial_rating: float | None = None)

Keener Ratings competitor.

Keener rates a connected population from the dominant eigenvector of a pairwise preference matrix built from points scored. Like Colley, Massey and Bradley-Terry – and unlike Elo – ratings are not nudged after each result; the whole connected group is re-fit from the complete match history, which makes the method order independent.

Scores. beat / lost_to / tied accept the common optional scores payload, the two competitors’ scores in caller order. Keener is a score-based method, so supplying real scores is what it is built for. When they are omitted the implementation falls back to the same unit scores the rest of the library uses: the winner is credited 1 and the loser 0, and a draw credits each side 0.5. Unit-score Keener still produces a sensible ranking, but it only sees who beat whom.

Key characteristics: - Global eigenvector fit (does not depend on the order of results) - Ratings are strictly positive and average exactly 1.0 within a connected group - Large margins have a damped, not linear, influence thanks to the skew transform

Class Attributes:

_minimum_rating (float): The minimum allowed rating value. Default: 0.0. Keener

ratings are strictly positive, so no Elo-style floor applies.

_default_initial_rating (float): Default initial rating. Default: 1.0, which is the

mean the fitted ratings are normalized to, so an unplayed competitor sits exactly at the population average.

_perturbation (float): Keener’s eps, added to every matrix entry so the matrix is

strictly positive and Perron-Frobenius applies. Default: 1e-4.

_expected_score_scale (float): Logistic scale applied to the log rating ratio by

expected_score(). Default: 1.0, which is the plain Keener share r_a / (r_a + r_b).

_round_decimals (int): Number of decimal places fitted ratings are canonicalized to,

so that solver noise cannot make mathematically identical records differ. Default: 10, chosen because the eigen-solve’s row-order noise is around 5e-15 – five orders of magnitude below the rounding grid.

Initialize a new Keener competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor.

Default: 1.0.

Raises:

InvalidRatingValueException: If the initial rating is not positive.

beat(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has won against the given competitor.

The scores are recorded in the match graph and the whole connected group is re-fit.

Args:

competitor (BaseCompetitor): The opponent competitor that lost. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). When omitted the unit scores 1 and 0 are recorded.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match. ValueError: If scores does not describe a win for this competitor.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score against another competitor.

Keener ratings are positive strengths rather than probabilities, so the natural mapping is the share r_self / (r_self + r_competitor). That share is computed here as a logistic of the log rating ratio, which is the same quantity written in a form that is exactly complementary in floating point: two equal ratings give exactly 0.5, and the two argument orders sum to exactly 1.0.

Args:

competitor (BaseCompetitor): The competitor to compare against.

Returns:

float: The expected score (probability of winning).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

This method exports the competitor’s state in a standardized format that can be used to recreate the competitor with the same state. The format includes: - type: The class name of the competitor - version: The version of the serialization format - created_at: The timestamp when the state was exported - id: A unique identifier for this state export - parameters: The parameters used to initialize the competitor - state: The current state variables of the competitor

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

tied(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has tied with the given competitor.

Args:

competitor (BaseCompetitor): The opponent competitor that tied. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). They must be equal. When omitted each side is credited the unit draw score 0.5.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match. ValueError: If scores does not describe a draw.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

Bradley-Terry Competitor

class elote.competitors.bradley_terry.BradleyTerryCompetitor(initial_rating: float | None = None)

Bradley-Terry model competitor.

The Bradley-Terry model assigns each competitor a latent strength and models the probability that one competitor beats another as a function of the difference of their log-strengths. Unlike Elo, which updates ratings incrementally, Bradley-Terry re-fits the strengths of every connected competitor via maximum likelihood after each result.

Ratings are reported on an Elo-like scale via rating = anchor + scale * beta, where beta is the internal log-strength (re-centered so the mean log-strength of a component is zero). Choosing scale = 400 / ln(10) makes expected_score() numerically identical to the Elo expected score, so ratings are directly comparable to Elo ratings.

Key characteristics: - Global maximum-likelihood fit (does not depend on the order of results) - Considers only wins and losses (ties are counted as half a win for each side) - Regularized so a unique, finite fit exists even for undefeated/winless competitors

Class Attributes:

_minimum_rating (float): The minimum allowed rating value. Default: 0.0. _anchor_rating (float): Rating assigned to the mean log-strength. Default: 1500.0. _scale (float): Points per unit of log-strength. Default: 400 / ln(10). _reg (float): Regularization strength (virtual wins/losses against an average

phantom opponent). Default: 0.1.

_max_iter (int): Maximum MM iterations per fit. Default: 10000. _tol (float): Convergence tolerance on the max change in log-strength. Default: 1e-8.

Initialize a new Bradley-Terry competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor, on the

Elo-like reporting scale. Default: the anchor rating (1500).

Raises:

InvalidParameterException: If the regularization or iteration parameters are invalid.

beat(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has won against the given competitor.

The result is recorded on both competitors and the strengths of the entire connected component are re-fit by maximum likelihood.

Args:

competitor (BaseCompetitor): The opponent competitor that lost. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Validated but not otherwise used by this rating system.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score against another competitor.

Args:

competitor (BaseCompetitor): The competitor to compare against.

Returns:

float: The expected score (probability of winning).

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

This method exports the competitor’s state in a standardized format that can be used to recreate the competitor with the same state. The format includes: - type: The class name of the competitor - version: The version of the serialization format - created_at: The timestamp when the state was exported - id: A unique identifier for this state export - parameters: The parameters used to initialize the competitor - state: The current state variables of the competitor

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor on the Elo-like reporting scale.

Returns:

float: The current rating.

tied(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has tied with the given competitor.

A tie is counted as half a win for each side.

Args:

competitor (BaseCompetitor): The opponent competitor that tied. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Must be equal. Validated but not otherwise used by this rating system.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

BlendedCompetitor

class elote.competitors.ensemble.BlendedCompetitor(competitors: List[Dict[str, Any]], blend_mode: str = 'mean')

Ensemble rating system that combines multiple rating algorithms.

The BlendedCompetitor allows combining multiple rating systems to leverage their individual strengths while mitigating their weaknesses. By aggregating predictions from different rating algorithms, it can potentially provide more robust and accurate predictions than any single rating system alone.

Supported blend modes:

• “mean”: Average the expected scores from all sub-competitors.

Initialize a BlendedCompetitor with multiple rating systems.

Args:

competitors (List[Dict[str, Any]]): List of dictionaries specifying the

sub-competitors to use. Each dictionary should have a “type” key with the name of the competitor class and a “competitor_kwargs” key with the arguments to pass to the constructor.

blend_mode (str, optional): The method to use for blending the ratings.

Currently only “mean” is supported. Default: “mean”.

Raises:

InvalidParameterException: If the blend_mode is not supported or if any

competitor specification is invalid.

beat(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has won against the given competitor.

This method updates the ratings of all sub-competitors based on the match outcome.

Args:

competitor (BaseCompetitor): The opponent competitor that lost. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Forwarded unchanged to every sub-competitor.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score (probability of winning) against another competitor.

For a BlendedCompetitor, the expected score is calculated by blending the expected scores from all sub-competitors according to the blend_mode.

Args:

competitor (BaseCompetitor): The opponent competitor to compare against.

Returns:

float: The probability of winning (between 0 and 1).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match. NotImplementedError: If the blend_mode is not supported.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the combined rating of this competitor.

For a BlendedCompetitor, the rating is the sum of all sub-competitor ratings. This is a simple way to represent the overall strength, but the expected_score method provides a more accurate way to compare competitors.

Returns:

float: The combined rating.

tied(competitor: BaseCompetitor, *, scores: Sequence[float] | None = None) → None

Update ratings after this competitor has tied with the given competitor.

This method updates the ratings of all sub-competitors based on the drawn match outcome.

Args:

competitor (BaseCompetitor): The opponent competitor that tied. scores (sequence of float, optional): The two scores in caller order,

(self_score, competitor_score). Must be equal. Forwarded unchanged to every sub-competitor.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

Serialization

All competitor types in Elote support a standardized serialization format that allows for saving and loading competitor states. The serialization format includes the following fields:

• type: The class name of the competitor

• version: The version of the serialization format

• created_at: Timestamp when the state was exported

• id: A unique identifier for this state export

• parameters: The parameters used to initialize the competitor

• state: The current state variables of the competitor

• class_vars: Class variables for backward compatibility

To serialize a competitor to JSON:

# Create a competitor
competitor = EloCompetitor(initial_rating=1500)

# Serialize to JSON
json_str = competitor.to_json()

To deserialize a competitor from JSON:

# Deserialize from JSON
competitor = EloCompetitor.from_json(json_str)

For backward compatibility, the serialized format also includes flattened parameters and state variables at the top level of the dictionary.