rstt.player package

Submodules

rstt.player.basicplayer module

class rstt.player.basicplayer.BasicPlayer(name: str | None = None, level: float | None = None)

Bases: object

Basic Player

BasicPlayer have a level and a name, that is it. The bare minimum for simulation to run. This class is usefull for when your player do not need to track their match history and do not have a time varying level.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelOptional[float], optional

The level/skill/strenght of the player. By default None, in this case a level is generated using a random distribution rstt.config.PLAYER_DIST with default parameters :class:`rstt.config.PLAYER_DIST_ARGS

classmethod create(nb: int, name_gen: Callable[[...], str] | None = None, name_params: Dict[str, Any] | None = None, level_dist: Callable[[...], float] | None = None, level_params: Dict | None = None)

Class method to generate multiple player at once.

Customizable method to generate a bunch of players with your favorite settings.

Parameters

nbint

The amount of player to create and return.

name_genCallable[…, str], optional

A name generator. By default None, in this case names are generated using the names package.

name_paramsDict[str, Any], optional

Kwargs to pass to the name_gen function, by default None.

level_distCallable[…, float], optional

A level generator. By default None, in this case it uses a random distribution specifed by rstt.config.PLAYER_DIST.

level_paramsDict, optional

Kwargs to pass to the level_dist. By default None, in this case it uses default parameters specified by rstt.config.PLAYER_DIST_ARGS

Returns

List[BasicPlayer]

A list of player.

level() → float

Getter method for the player’s level

Returns

float

The level of the player.

name() → str

Getter method for the name of the player

Returns

str

The name of the player

classmethod seeded_players(nb: int, start: int = 0, inc: float = 100)

Create ‘seeded’ players

Unlike the rstt.player.basicplayer.BasicPlayer.create() method, players generated have a deterministic name and level. Names are of the form f”Seed_{i}”, and the lowest i, the higher the level of the player.

Warning

The rstt package relies on player’s name to identify them - there is no ID. This method can result in name clashing which may lead to confusion and unexpected bahaviour accross simulations. It is heavly recommanded to be carefull when calling this method multiple times. Either by tuning the ‘start’ parameter or deleting previously created player.

Parameters

nbint

The amount of player to create and return.

startint, optional

The first ‘i’ for the name of players, by default 0.

incfloat, optional

The difference of level between playery Seed_i and Seed_i+1, by default 100.

Returns

List[BasicPlayer]

A list of seeded player in desceding order of level.

rstt.player.basicplayer.create(cls, nb: int, name_gen: Callable[[...], str] | None = None, name_params: Dict[str, Any] | None = None, level_dist: Callable[[...], float] | None = None, level_params: Dict | None = None)

Class method to generate multiple player at once.

Customizable method to generate a bunch of players with your favorite settings.

Parameters

nbint

The amount of player to create and return.

name_genCallable[…, str], optional

A name generator. By default None, in this case names are generated using the names package.

name_paramsDict[str, Any], optional

Kwargs to pass to the name_gen function, by default None.

level_distCallable[…, float], optional

A level generator. By default None, in this case it uses a random distribution specifed by rstt.config.PLAYER_DIST.

level_paramsDict, optional

Kwargs to pass to the level_dist. By default None, in this case it uses default parameters specified by rstt.config.PLAYER_DIST_ARGS

Returns

List[BasicPlayer]

A list of player.

rstt.player.basicplayer.seeded_players(cls, nb: int, start: int = 0, inc: float = 100)

Create ‘seeded’ players

Unlike the rstt.player.basicplayer.BasicPlayer.create() method, players generated have a deterministic name and level. Names are of the form f”Seed_{i}”, and the lowest i, the higher the level of the player.

Warning

The rstt package relies on player’s name to identify them - there is no ID. This method can result in name clashing which may lead to confusion and unexpected bahaviour accross simulations. It is heavly recommanded to be carefull when calling this method multiple times. Either by tuning the ‘start’ parameter or deleting previously created player.

Parameters

nbint

The amount of player to create and return.

startint, optional

The first ‘i’ for the name of players, by default 0.

incfloat, optional

The difference of level between playery Seed_i and Seed_i+1, by default 100.

Returns

List[BasicPlayer]

A list of seeded player in desceding order of level.

rstt.player.gaussian module

class rstt.player.gaussian.GaussianPlayer(name: str | None = None, mu: float | None = None, sigma: float | None = None)

Bases: PlayerTVS

Player with a level following a gaussian distribution

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

mufloat, optional

The player’s mean level, also considered as the ‘original’ level. By default None, in this case a level is generated using a random distribution rstt.config.GAUSSIAN_PLAYER_MEAN_DIST with default parameters :class:`rstt.config.GAUSSIAN_PLAYER_MEAN_ARGS

sigmafloat, optional

The player’s level standard deviation. By default None, in this case a random value is generated using a random distribution rstt.config.GAUSSIAN_PLAYER_SIGMA_DIST with default parameters :class:`rstt.config.GAUSSIAN_PLAYER_SIGMA_ARGS

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

rstt.player.player module

class rstt.player.player.Player(name: str | None = None, level: float | None = None)

Bases: BasicPlayer

Player with match history.

Player extends rstt.player.basicPlayer.BasicPlayer with the possibility to track games it played in and by collecting results achieved in rstt.stypes.Achievement.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelfloat, optional

The level/skill/strenght of the player. By default None, in this case a level is randomly generated. using a random distribution rstt.config.PLAYER_DIST with default parameters :class:`rstt.config.PLAYER_DIST_ARGS

achievements() → List[Achievement]

Getter method for achievement

rstt.stypes.Achievement represent tournament result of the player.

Returns

List[Achievement]

All past success of the player in chronological order, from the oldest to the most recent.

add_game(match: Match) → None

Adds match to the player history

Parameters

matchMatch

A match to track.

Raises

ValueError

The match needs to be a game in which the player partipiated in and not already tracked. Either condition violated will raise an Error.

collect(achievement: Achievement | List[Achievement])

Adds achivement(s) to the player history.

Parameters

achievementUnion[Achievement, List[Achievement]]

Achievement(s) passed must have a different event_name attribute that the one already stored.

Raises

ValueError

Raised when attempting to collect an event with an event_name already present in the player history.

earnings() → float

Getter method for the earnings

Sugar method that returns the sum of earnings specified by the player achievements.

Returns

float

All the money earned in competitif event.

games() → List[Match]

Getter method for match the player participated in

Returns

List[Match]

All the matches the player played in chronolgical order, from oldest to the most recent.

reset(games: bool = True, achievement: bool = True) → None

Clean the player history

Removes all matchs and achievements from the players history.

Parameters

gamesbool, optional

Wether matchs should be removed, by default True.

achievementbool, optional

Wether achievements should be removed, by default True.

rstt.player.player.add_game(self, match: Match) → None

Adds match to the player history

Parameters

matchMatch

A match to track.

Raises

ValueError

The match needs to be a game in which the player partipiated in and not already tracked. Either condition violated will raise an Error.

rstt.player.player.collect(self, achievement: Achievement | List[Achievement])

Adds achivement(s) to the player history.

Parameters

achievementUnion[Achievement, List[Achievement]]

Achievement(s) passed must have a different event_name attribute that the one already stored.

Raises

ValueError

Raised when attempting to collect an event with an event_name already present in the player history.

rstt.player.player.reset(self, games: bool = True, achievement: bool = True) → None

Clean the player history

Removes all matchs and achievements from the players history.

Parameters

gamesbool, optional

Wether matchs should be removed, by default True.

achievementbool, optional

Wether achievements should be removed, by default True.

rstt.player.playerTVS module

class rstt.player.playerTVS.CyclePlayer(name: str | None = None, level: float | None = None, sigma: float | None = None, tau: int | None = None)

Bases: PlayerTVS

Cycle Player

Implement the ‘Cycle Model’ descirbed by Aldous D. in ‘Elo ratings and the Sports Model: A Negleted Topic in Applied Probability?’ [section 4.1]

Cycle player have a deterministic level evolution in cycle. The variance of the level is given by the attribute __sigma^2, while the attribute __tau indicates the number of game needed for the level to decrease from its maximum to its avergae value.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelfloat, optional

The mean level, by default None, int this case a level is randomly generated

sigmafloat, optional

The standard deviation of the level, by default 1.0

tauint, optional

The number of update needed for a level to decrease from its maximal value to its mean level, by default 100

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

class rstt.player.playerTVS.ExponentialPlayer(name: str | None = None, start: float | None = None, final: float | None = None, tau: float | None = None)

Bases: PlayerTVS

Player with a level that tends to a final value.

The transition to the final level is controlled by an exponential decay function.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

startfloat, optional

The initial level of the player. By default None, in this case a level is randomly generated.

finalfloat, optional

The final level of the player. By default None, in this case a level is randomly generated.

taufloat, optional

Controls how fast (number of level update) the player’s level gets close to its final level.

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

class rstt.player.playerTVS.JumpPlayer(name: str | None = None, level: float | None = None, sigma: float | None = None, tau: int | None = None)

Bases: PlayerTVS

Jump Player

Implement a ‘Jump Model’ adapted from Aldous D. in ‘Elo ratings and the Sports Model’ [section 4.3] The implementation differs from the source document by allowing a player to ‘jumpe’ mulitple times as simulation progress, and not just once.

A JumpPlayer level remains constant for an amount of time given by a geometric distribution before ‘jumping’ to a new level given by a Normal distribution.

In practice, calling the rstt.player.playerTVS.PlayerTVS.update_level() will often result in no level changes.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelfloat, optional

The initial level, by default None, int this case a level is randomly generated.

sigmafloat, optional

Standard deviantion of the level changes, by default 1.0. Remark that the mean level changes is 0, as a consequences the player’s level as equal chances to increase or decrease.

tauint, optional

Parameter of the geometric distribution, by default 400. This will tune the tendancy that a player has to stay at a level before the level is updated.

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

class rstt.player.playerTVS.LogisticPlayer(name: str | None = None, start: float | None = None, final: float | None = None, center_x: float | None = None, r: float | None = None)

Bases: PlayerTVS

Player with a level that tends to a final value.

The transition to the final level is controlled by a logistic function.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

startfloat, optional

The initial level of the player. By default None, in this case a level is randomly generated.

finalfloat, optional

The final level of the player. By default None, in this case a level is randomly generated.

center_xfloat, optional

Number of level update for the player to reach the level:=(final-start)/2, by default 100.

rfloat, optional

Controls the sharpness of the level transition, by default 0.5.

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

class rstt.player.playerTVS.PlayerTVS(name: str | None = None, level: float | None = None)

Bases: Player

Player with time varying level.

The class introduce a mechanism for Player to change their level during simulation while maintaining the ability to track their match properly. Their is only one abstract method to implement when inheriting from it, the rstt.player.playerTVS.PlayerTVS._update_level()

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelfloat, optional

The level/skill/strenght of the player. By default None, in this case a level is randomly generated.

add_game(*args, **kwars) → None

Adds match to the player history

Parameters

matchMatch

A match to track.

Raises

ValueError

The match needs to be a game in which the player partipiated in and not already tracked. Either condition violated will raise an Error.

games() → list[SMatch]

Getter method for match the player participated in

Returns

List[Match]

All the matches the player played in chronolgical order, from oldest to the most recent.

level() → float

Getter method for the player’s level

Returns

float

The current level of the player.

level_history() → List[float]

Getter for the player’s level’s evolution.

Returns

List[float]

All the level the player had in chronological order

level_in(game: SMatch) → float

The level a player displayed in a given game

Parameters

gameSMatch

A match to query the player’s level in.

Returns

float

The player’s level in the given game.

original_level() → float

The first level

Sugar for PlayerTVS.level_history()[0]

Returns

float

The original level (at instanciation)

reset()

Clean the player history

Removes all matchs and achievements from the players history.

Parameters

gamesbool, optional

Wether matchs should be removed, by default True.

achievementbool, optional

Wether achievements should be removed, by default True.

update_level(*args, **kwars) → None

Method to update the player’s level

Module contents

Modules defining SPlayer

SPlayer is the notion of competitors facing each others. They are elemts of rstt.ranking.ranking.Ranking, and participants in rstt.stypes.SMatch

class rstt.player.BasicPlayer(name: str | None = None, level: float | None = None)

Bases: object

Basic Player

BasicPlayer have a level and a name, that is it. The bare minimum for simulation to run. This class is usefull for when your player do not need to track their match history and do not have a time varying level.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelOptional[float], optional

The level/skill/strenght of the player. By default None, in this case a level is generated using a random distribution rstt.config.PLAYER_DIST with default parameters :class:`rstt.config.PLAYER_DIST_ARGS

classmethod create(nb: int, name_gen: Callable[[...], str] | None = None, name_params: Dict[str, Any] | None = None, level_dist: Callable[[...], float] | None = None, level_params: Dict | None = None)

Class method to generate multiple player at once.

Customizable method to generate a bunch of players with your favorite settings.

Parameters

nbint

The amount of player to create and return.

name_genCallable[…, str], optional

A name generator. By default None, in this case names are generated using the names package.

name_paramsDict[str, Any], optional

Kwargs to pass to the name_gen function, by default None.

level_distCallable[…, float], optional

A level generator. By default None, in this case it uses a random distribution specifed by rstt.config.PLAYER_DIST.

level_paramsDict, optional

Kwargs to pass to the level_dist. By default None, in this case it uses default parameters specified by rstt.config.PLAYER_DIST_ARGS

Returns

List[BasicPlayer]

A list of player.

level() → float

Getter method for the player’s level

Returns

float

The level of the player.

name() → str

Getter method for the name of the player

Returns

str

The name of the player

classmethod seeded_players(nb: int, start: int = 0, inc: float = 100)

Create ‘seeded’ players

Unlike the rstt.player.basicplayer.BasicPlayer.create() method, players generated have a deterministic name and level. Names are of the form f”Seed_{i}”, and the lowest i, the higher the level of the player.

Warning

The rstt package relies on player’s name to identify them - there is no ID. This method can result in name clashing which may lead to confusion and unexpected bahaviour accross simulations. It is heavly recommanded to be carefull when calling this method multiple times. Either by tuning the ‘start’ parameter or deleting previously created player.

Parameters

nbint

The amount of player to create and return.

startint, optional

The first ‘i’ for the name of players, by default 0.

incfloat, optional

The difference of level between playery Seed_i and Seed_i+1, by default 100.

Returns

List[BasicPlayer]

A list of seeded player in desceding order of level.

class rstt.player.CyclePlayer(name: str | None = None, level: float | None = None, sigma: float | None = None, tau: int | None = None)

Bases: PlayerTVS

Cycle Player

Implement the ‘Cycle Model’ descirbed by Aldous D. in ‘Elo ratings and the Sports Model: A Negleted Topic in Applied Probability?’ [section 4.1]

Cycle player have a deterministic level evolution in cycle. The variance of the level is given by the attribute __sigma^2, while the attribute __tau indicates the number of game needed for the level to decrease from its maximum to its avergae value.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelfloat, optional

The mean level, by default None, int this case a level is randomly generated

sigmafloat, optional

The standard deviation of the level, by default 1.0

tauint, optional

The number of update needed for a level to decrease from its maximal value to its mean level, by default 100

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

class rstt.player.ExponentialPlayer(name: str | None = None, start: float | None = None, final: float | None = None, tau: float | None = None)

Bases: PlayerTVS

Player with a level that tends to a final value.

The transition to the final level is controlled by an exponential decay function.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

startfloat, optional

The initial level of the player. By default None, in this case a level is randomly generated.

finalfloat, optional

The final level of the player. By default None, in this case a level is randomly generated.

taufloat, optional

Controls how fast (number of level update) the player’s level gets close to its final level.

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

class rstt.player.GaussianPlayer(name: str | None = None, mu: float | None = None, sigma: float | None = None)

Bases: PlayerTVS

Player with a level following a gaussian distribution

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

mufloat, optional

The player’s mean level, also considered as the ‘original’ level. By default None, in this case a level is generated using a random distribution rstt.config.GAUSSIAN_PLAYER_MEAN_DIST with default parameters :class:`rstt.config.GAUSSIAN_PLAYER_MEAN_ARGS

sigmafloat, optional

The player’s level standard deviation. By default None, in this case a random value is generated using a random distribution rstt.config.GAUSSIAN_PLAYER_SIGMA_DIST with default parameters :class:`rstt.config.GAUSSIAN_PLAYER_SIGMA_ARGS

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

class rstt.player.JumpPlayer(name: str | None = None, level: float | None = None, sigma: float | None = None, tau: int | None = None)

Bases: PlayerTVS

Jump Player

Implement a ‘Jump Model’ adapted from Aldous D. in ‘Elo ratings and the Sports Model’ [section 4.3] The implementation differs from the source document by allowing a player to ‘jumpe’ mulitple times as simulation progress, and not just once.

A JumpPlayer level remains constant for an amount of time given by a geometric distribution before ‘jumping’ to a new level given by a Normal distribution.

In practice, calling the rstt.player.playerTVS.PlayerTVS.update_level() will often result in no level changes.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelfloat, optional

The initial level, by default None, int this case a level is randomly generated.

sigmafloat, optional

Standard deviantion of the level changes, by default 1.0. Remark that the mean level changes is 0, as a consequences the player’s level as equal chances to increase or decrease.

tauint, optional

Parameter of the geometric distribution, by default 400. This will tune the tendancy that a player has to stay at a level before the level is updated.

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

class rstt.player.LogisticPlayer(name: str | None = None, start: float | None = None, final: float | None = None, center_x: float | None = None, r: float | None = None)

Bases: PlayerTVS

Player with a level that tends to a final value.

The transition to the final level is controlled by a logistic function.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

startfloat, optional

The initial level of the player. By default None, in this case a level is randomly generated.

finalfloat, optional

The final level of the player. By default None, in this case a level is randomly generated.

center_xfloat, optional

Number of level update for the player to reach the level:=(final-start)/2, by default 100.

rfloat, optional

Controls the sharpness of the level transition, by default 0.5.

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

class rstt.player.Player(name: str | None = None, level: float | None = None)

Bases: BasicPlayer

Player with match history.

Player extends rstt.player.basicPlayer.BasicPlayer with the possibility to track games it played in and by collecting results achieved in rstt.stypes.Achievement.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelfloat, optional

The level/skill/strenght of the player. By default None, in this case a level is randomly generated. using a random distribution rstt.config.PLAYER_DIST with default parameters :class:`rstt.config.PLAYER_DIST_ARGS

achievements() → List[Achievement]

Getter method for achievement

rstt.stypes.Achievement represent tournament result of the player.

Returns

List[Achievement]

All past success of the player in chronological order, from the oldest to the most recent.

add_game(match: Match) → None

Adds match to the player history

Parameters

matchMatch

A match to track.

Raises

ValueError

The match needs to be a game in which the player partipiated in and not already tracked. Either condition violated will raise an Error.

collect(achievement: Achievement | List[Achievement])

Adds achivement(s) to the player history.

Parameters

achievementUnion[Achievement, List[Achievement]]

Achievement(s) passed must have a different event_name attribute that the one already stored.

Raises

ValueError

Raised when attempting to collect an event with an event_name already present in the player history.

earnings() → float

Getter method for the earnings

Sugar method that returns the sum of earnings specified by the player achievements.

Returns

float

All the money earned in competitif event.

games() → List[Match]

Getter method for match the player participated in

Returns

List[Match]

All the matches the player played in chronolgical order, from oldest to the most recent.

reset(games: bool = True, achievement: bool = True) → None

Clean the player history

Removes all matchs and achievements from the players history.

Parameters

gamesbool, optional

Wether matchs should be removed, by default True.

achievementbool, optional

Wether achievements should be removed, by default True.

class rstt.player.PlayerTVS(name: str | None = None, level: float | None = None)

Bases: Player

Player with time varying level.

The class introduce a mechanism for Player to change their level during simulation while maintaining the ability to track their match properly. Their is only one abstract method to implement when inheriting from it, the rstt.player.playerTVS.PlayerTVS._update_level()

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelfloat, optional

The level/skill/strenght of the player. By default None, in this case a level is randomly generated.

add_game(*args, **kwars) → None

Adds match to the player history

Parameters

matchMatch

A match to track.

Raises

ValueError

The match needs to be a game in which the player partipiated in and not already tracked. Either condition violated will raise an Error.

games() → list[SMatch]

Getter method for match the player participated in

Returns

List[Match]

All the matches the player played in chronolgical order, from oldest to the most recent.

level() → float

Getter method for the player’s level

Returns

float

The current level of the player.

level_history() → List[float]

Getter for the player’s level’s evolution.

Returns

List[float]

All the level the player had in chronological order

level_in(game: SMatch) → float

The level a player displayed in a given game

Parameters

gameSMatch

A match to query the player’s level in.

Returns

float

The player’s level in the given game.

original_level() → float

The first level

Sugar for PlayerTVS.level_history()[0]

Returns

float

The original level (at instanciation)

reset()

Clean the player history

Removes all matchs and achievements from the players history.

Parameters

gamesbool, optional

Wether matchs should be removed, by default True.

achievementbool, optional

Wether achievements should be removed, by default True.

update_level(*args, **kwars) → None

Method to update the player’s level