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. When omitted the

competitor has no recorded activity and adopts the time of its first match, so a stream of historical results can be replayed through it.

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. When omitted the

competitor has no recorded activity and adopts the time of its first match, so a stream of historical results can be replayed through it.

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.

Glicko-Boost Competitor

class elote.competitors.glicko_boost.GlickoBoostCompetitor(initial_rating: float = 1500, initial_rd: float = 250, initial_time: datetime | None = None)

Glicko-Boost rating system competitor.

Glicko-Boost is Mark Glickman’s extension of Glicko, described in Glicko-Boost. Unlike Elo or Glicko it is defined over a whole rating period rather than over one game: the population is updated twice from the same pre-period ratings, players whose performance was exceptional have their pre-period RD boosted, and the pair of updates is then repeated. This class therefore overrides apply_rating_period() and is the first shipped system whose period update is not a replay of pairwise results.

The six steps applied to one period are:

1. Glicko updating of every player from the pre-period ratings and RDs, with a white-advantage term inside E().

2. The same update from the pre-period ratings, but against the opponents’ step 1 ratings and RDs.

3. An RD boost for players whose performance z-score exceeds k.

4. Step 1 again, using the boosted RDs.

5. Step 2 again, using the step 4 results. These are the period’s final ratings.

6. An RD increase for the passage of time, applied when the competitor next takes part in a period (the way GlickoCompetitor handles inactivity), so a competitor that sits out periods catches up on its next appearance.

Colour is carried by argument order rather than by a new parameter: in a rating period row (a, b, outcome, scores) – and in a.beat(b), a.lost_to(b) or a.tied(b) – a is white. Callers with no colour information leave _eta at its default of 0.0, which removes the white-advantage term entirely.

elote.LambdaArena.matchup() is the exception: it dispatches a loss by calling beat on the winner, so the losing row’s colours are reversed relative to the same row given to apply_rating_period(). That only matters when _eta is non-zero; drive colour-bearing data through elote.LambdaArena.rating_period() instead.

beat/lost_to/tied apply the same algorithm to a one-game period, so a single result is never a different formula from a batch. Because of the two-pass structure a lone pairwise call is not identical to a Glicko update.

Class Attributes:

_q (float): ln(10)/400, the Glicko scaling constant. _eta (float): Rating advantage for playing white. Default: 0.0; Glickman’s is 30.0. _b1 (float): RD boost multiplicative factor. Default: 0.20139. _b2 (float): RD boost additive factor. Default: 17.5. _k (float): The z-score above which an RD is boosted. Default: 1.96. _alpha0 .. _alpha4 (float): RD-increase-over-time coefficients, at Glickman’s values. _rd_unrated (float): The RD cap, RD_unr in the paper. Default: 250.0. _rating_period_days (float): Days in one rating period. Default: 30.0 (a month).

Initialize a Glicko-Boost competitor.

Args:

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

Glickman’s FIDE-specific default for an unrated player is 1946.25.

initial_rd (float, optional): The initial rating deviation. Default: 250, the

paper’s RD_unr.

initial_time (datetime, optional): The initial timestamp for this competitor. When

omitted the competitor has no recorded activity and adopts the time of its first period, so historical results can be replayed through it.

Raises:

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

classmethod apply_rating_period(results: Sequence[Tuple[BaseCompetitor, BaseCompetitor, float, Sequence[float] | None]], *, period_end: Any | None = None) → None

Apply results that share one rating period, using Glicko-Boost’s own period update.

This is where the whole algorithm lives: the pairwise methods route a single result through here as a one-game period, so every caller gets the same formulas.

Args:

results: (white, black, outcome, scores) tuples. Outcomes use 1.0 for a

white win, 0.0 for a black win and 0.5 for a draw; scores follow the usual optional caller-order contract and are validated but not consumed.

period_end: The shared activity time for the period. Elapsed rating periods since

each participant’s last activity inflate its RD before the update.

Raises:

ValueError: If an outcome or score payload is invalid. MissMatchedCompetitorTypesException: If a row contains another rating system.

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.

The result is applied as a one-game rating period in which this competitor had white.

Args:

competitor (BaseCompetitor): The opponent competitor that lost. match_time (datetime, optional): The time of the match, used as the period’s end. scores (sequence of float, optional): The two scores in caller order. Validated only.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

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

This uses the paper’s own approximation, which combines the two rating deviations rather than using only the opponent’s. With _eta at its default of 0.0 the result is exactly complementary: a.expected_score(b) + b.expected_score(a) == 1.

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.

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, match_time: datetime | None = None, *, scores: Sequence[float] | None = None) → None

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

Args:

competitor (BaseCompetitor): The opponent competitor that drew. match_time (datetime, optional): The time of the match, used as the period’s end. scores (sequence of float, optional): The two scores in caller order. Must be equal.

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.

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 mu is not finite or sigma is not finite and 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 the ratings of all related competitors are re-fit lazily, on the next rating read.

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.

Reading the rating is where deferred matrix solves happen: if games have been recorded since the last read, the connected group is re-fit first.

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

Rating scale. Because the rating difference carries the caller’s own units, every fit also records _rating_scale, the spread of the connected group’s ratings. expected_score() divides by it, so the win probabilities do not change when the same schedule is expressed in different point units, and do not saturate to 0.0/1.0 when real point margins put the ratings on a points-per-game scale. It is 1.0 for a competitor that has never been fitted, and it survives export_state() / from_state().

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): Dimensionless sharpness multiplier used by

expected_score(). The rating difference is divided by the fitted rating spread before it reaches the logistic, so this constant does not depend on the units the caller’s scores are in. 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 lazily, on the next rating read.

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. Because that margin is in whatever units the caller’s scores are in – unit margins when scores is omitted, points per game when it is supplied – the difference is first divided by the fitted rating spread (the root-mean-square rating difference within the connected group, see _update_rating_scale()). That makes the logistic argument dimensionless and leaves _expected_score_scale a pure sharpness knob. 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.

Reading the rating is where deferred least-squares solves happen: if games have been recorded since the last read, the connected group is re-fit first.

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.

_games_prior (float): Pseudo-games added to the games-played denominator, shrinking a

competitor’s average preference toward zero in proportion to how little evidence backs it. Default: 2.0, matching the two pseudo-observations the Laplace-smoothed score share already assumes. Without it, a competitor with a single game puts all of its row weight on one opponent and the dominant eigenvector rewards that concentration, so a one-game team can outrate an undefeated one.

_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 lazily, on the next rating read.

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.

Reading the rating is where deferred eigenvector fits happen: if games have been recorded since the last read, the connected group is re-fit first.

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.

Pythagorean Competitor

class elote.competitors.pythagorean.PythagoreanCompetitor(exponent: float | None = None)

Pythagorean expectation competitor.

Rates a competitor from the points it has scored and the points it has allowed. Unlike Colley, Massey, Keener and Bradley-Terry, nothing is fitted across a population: each result adds to two running totals, and the rating is read straight off them. Unlike Elo and the other incremental systems, the update does not depend on the opponent at all.

Scores. beat / lost_to / tied accept the common optional scores payload, the two competitors’ scores in caller order. Points are what this system is built on, so supplying real ones is the intended use. When they are omitted the same unit-score fallback the rest of the library uses applies: the winner is credited 1 and the loser 0, and a draw credits each side 0.5. On unit scores the rating degenerates into a smoothed winning percentage, which is still a usable baseline.

Degenerate inputs. A fresh competitor has PF = PA = 0 and an unbeaten one has PA = 0; the first makes the rating 0/0 and the second makes it exactly 1, which in turn makes log5 0/0. Both are handled by a small symmetric prior added to each accumulator rather than by clamping the output: the rating stays a continuous, strictly monotone function of the real totals, a fresh competitor is exactly 0.5, and every rating is strictly inside (0, 1), so log5 is always defined.

Key characteristics: - The rating is a win expectation in [0, 1], not a strength score - Constant-time update: no opponent graph, no refit, no order dependence - Reads real scores; falls back to unit scores when they are omitted - Makes no strength-of-schedule adjustment whatsoever

Class Attributes:

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

is a probability, so the inherited Elo-style floor of 100 would saturate it.

_default_initial_rating (float): The rating of a competitor that has not played.

Default: 0.5, which the symmetric prior produces exactly.

_exponent (float): Pythagorean k. Default: 2.37, the standard fit for American

football (Football Outsiders). Use 2 for baseball, or a much larger value for a high-scoring sport such as basketball.

_prior_points (float): The symmetric prior added to both accumulators, in points.

Default: 1.0 – comparable to the unit scores, negligible against real ones.

Initialize a Pythagorean competitor.

There is deliberately no initial_rating argument: the rating is derived from the points totals rather than stored, and a caller-supplied starting rating on a [0, 1] scale has no points totals that would produce it.

Args:

exponent (float, optional): The Pythagorean exponent for this competitor. If

None, the class exponent is used. Default: None.

Raises:

InvalidParameterException: If the exponent 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). 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.

Both ratings are already win expectations, so they are combined with the standard log5 formula. The direction with the larger rating is the one actually computed and the other is taken as its complement, which makes the two argument orders sum to exactly 1.0 and makes two equal ratings give exactly 0.5.

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.

The rating is the Pythagorean win expectation PF^k / (PF^k + PA^k), computed on the prior-adjusted totals. It is evaluated in the equivalent ratio form 1 / (1 + (PA/PF)^k), which cannot overflow for large totals and returns exactly 0.5 whenever the two totals are equal.

Returns:

float: The current rating, strictly inside (0, 1).

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.

Whole-History Rating Competitor

class elote.competitors.whr.WholeHistoryRatingCompetitor(w2: float | None = None, initial_rating: float | None = None, max_iterations: int | None = None, precision: float | None = None)

A time-aware Bradley-Terry maximum-a-posteriori rating curve.

One latent rating is kept for every distinct playing day. Consecutive ratings are linked by a Wiener-process prior whose variance is w2 * elapsed_days in Elo points squared. Results use the Bradley-Terry likelihood, and a bounded sequence of per-competitor tridiagonal Newton updates fits the connected component lazily.

Serialized state preserves the fitted per-day curve and day index, but cannot preserve object references in the game graph. On the first result after restore, the latest restored rating becomes the initial rating of a fresh history; restored lifetime games are therefore never silently combined with a reset graph.

Args:

w2: Per-day Wiener-process variance in Elo points squared. initial_rating: Rating before any games, on the Elo scale. max_iterations: Maximum component-wide Newton sweeps per lazy fit. precision: Stop when the largest Elo-scale Newton step is below this value.

Reference: Coulom, R. (2008), Whole-History Rating: A Bayesian Rating System for Players of Time-Varying Strength.

Initialize base competitor state.

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 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 non-negative, finite scores in

caller order – (self_score, competitor_score). Rating systems that model margin of victory (such as MasseyCompetitor) consume it; the rest validate and ignore it. When omitted, every system falls back to its documented unit-score behaviour.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match. ValueError: If scores is malformed, negative, non-finite, or does not describe

a win for this competitor.

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.

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 value of this competitor.

Returns:

float: The current rating value.

rating_at(when: datetime | date) → float

Return the fitted rating on, or most recently before, when.

rating_history() → List[Tuple[date, float]]

Return a chronological copy of the fitted (day, rating) curve.

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 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). They must be equal, since the result is declared a draw.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match. ValueError: If scores is malformed, negative, non-finite, or is not a draw.

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.