Documentation¶

At this point in time the package contains four primary classes and two child classes which will are documented in this section.

Player¶

A player class used to represent any sports team/person that will go onto compete in competitions of a classic 1v1 elemination tournament. A subclass bye exists to models byes, for the situations where there are not enough players for the format and so byes can be added.

class synthSportPlayer.player(skill, variance, name, pointLimit=10)¶

A class to model any sports player/team.

Parameters

skill (int or float) – The underlying ‘true’ skill of a player
variance (int or float) – How much the player varies in their performance. The lower this is the more consistent they are in their performance
name (str) – The players name/id that will be used as a reference later on
pointLimit (int, default 10) – The max number of points a player is allowed to keep in the pointRec.

pointRec¶

A record of the points the this player has earnt from a tournament in the order that they earnt them.

Type: list of int

totalPoints¶

The total of all the points in pointRec.

Type: int

gainPoints(points)¶

A method to update the current points of the player.

The points provided are added to the players pointRec. If the number of entries in the pointRec is greater than pointLimit, then the oldest entry is removed. After this the totalPoints arrtibute is updated with the new total of pointRec.

Parameters: points (int) – Points to be added to the players pointRec.

perform()¶

A method getting the player to perform.

A numerical value is returned representing the players performance ‘on the day’. This is generate from a normal dist. with mean equal to the players skill and var equal to the player variance, which is then rounded to the nearest integer.

Returns: performance – The value representing the player performance on the day, which is greater than or equal to 0.
Return type: int

selfsummary()¶: A method to print out the characteristics of the player.

class synthSportPlayer.bye¶

Bases: synthSportPlayer.sportplayer.player

A class to model a bye.

In some tournaments there are not enough player, so the empty spots are filled up with a bye. Whenever a player is against a bye they automatically win.

perform()¶

A method getting the player to perform.

A numerical value is returned representing the players performance ‘on the day’. This is generate from a normal dist. with mean equal to the players skill and var equal to the player variance, which is then rounded to the nearest integer.

Returns: performance – The value representing the player performance on the day, which is greater than or equal to 0.
Return type: int

Match¶

A match class to represent to represent two players competing against each other where one will win and the other loses.

class synthSportPlayer.match(player1, player2)¶

A class to handle the match between two player’s or any bye.

Parameters

player1 (player or bye) – The first player or bye that is participating in the match.
player2 (player or bye) – The second player or bye that is participating in the match.

playMatch()¶

A method to excute the match between the two player’s given to the match.

Both the perform methods of the players are activated and the player with the higher performance score is the winner. If the two values are equal, then a winner is randomly chosen. If the match is a player vs a bye then the player automatically wins

Returns

winner (player or bye) – The player who won the match. A bye is only returned if the match is between 2 byes.
loser (player or bye) – The player who lost the match
matchReport (list) – A list containing the information from the match it has just played out. Containing for both players: their name, their total points, their performance value for that match. Then finally the name of the player who won.

Tournaments¶

Classes that represents a tournament that a collection of players enter and then proceed to compete until there is only one player who has won it all. Here we have two main classes tournament which model 1v1 elimination tournaments. the other robin which models Round bin tournaments.

class synthSportPlayer.tournament(playerList, pointPerRound=5)¶

A class to model a tournament

The tournament is the classic 1v1 elimination tournament where the winner of a match proceeds through to the next round.

Parameters

playerList (list of player) – A list containg the players who are competing in this tournament. If this is not a power of 2 then byes will be added to make up the numbers then then the list of players shuffled.
pointPerRound (int, default 5) – The number of points that a player earns at each stage that they get to.

matchRec¶

A list where the match results are stored when they are completed.

Type: list of list

round¶

An integer used to track what current round the tournament is in.

Type: int

tournRes¶

A pandas dataframe that is created and assigned once the tournament is complete containing all the match results, made from the matchRec attribute.

Type: DataFrame

playRound()¶

A method to play all the matches in the current round.

This plays out the round with the players that have made it through to the current stage. Each match result is added to the matchRec, and the loser gains points equal to the round where they got to.

Returns: nextRound – A list of players who won their matches and proceed through to the next round
Return type: list of players

playTourn()¶

A method to play the entire tournament.

Activating this method will play out the tournament until there is one player remaining as the winner. At which point the final tournament results are created and stored in tournRes.

reset()¶: A method to reset the tournament to be able to be played again.

class synthSportPlayer.liveTourn(playerList, pointPerRound=5)¶

Bases: synthSportPlayer.sportplayer.tournament

A class to facilitate live dashboarding of a season/tournament being played

For further info see the parent class tournament.

playTourn()¶

A method to play the tournament.

Unlike it’s parent class, when this method is called it will only play the next round of the tournament.

Returns: complete – A boolean to indicate if the tournament is now complete.
Return type: bool

class synthSportPlayer.robin(playerList, pointPerWin=5)¶

A class to model a round robin tournament.

A round robin is a variation on a tournament setting where all the players play against each other. The winner is normally the one with the most matches. If there’s any a draw it then goes to their win difference.

Parameters

playerList (list of player) – The players who are to play in this this round robin. If there is an odd number of players, a bye will be added in.
pointPerWin (int, default 5) – The number of points that players will recieve at the end of the tournament for each win.

numPlayers¶

The number of players that are competing in this round robin.

Type: int

matchRec¶

A list where the match results are stored when they are completed.

Type: list of list

round¶

An integer used to track what current round the tournament is in.

Type: int

tournRec¶

A pandas dataframe that is created and assigned once the tournament is complete containing all the match results, made from the matchRec attribute.

Type: DataFrame

winLossRec¶

A pandas dataframe containing the number of wins, losses and the winning point difference for each player

Type: DataFrame

distributePoints()¶

A method to distribute the points.

For each match a player has won, the value that is stored in the corresponding entry of winLossRec, they will gain points equal to pointPerWin.

permute()¶

Permute the order of the players for the next round of the round robin.

For a round robin you have to permute the players in a certain way to make everyone play everyone else.

playRound()¶

A method to play all the matches in the current round.

This plays out the round with the players against their allocated opponent for the current round. Each match result is added to the matchRec, and the winLossRec is updated with the results, unless it is against a bye

playTourn()¶

A method to play the entire tournament.

Activating this method will play out the tournament until every player has played everyother player. At which point the final tournament results are created and stored in tournRec. Points are then given to the players in accordance with how many matches they won.

reset()¶: A method to reset the tournament.

Seasons¶

A class the represents a season, which is in essence a sequence of tournaments where the players play one after another and collect points based on how far they got.

class synthSportPlayer.season(numPlayers=16, tournToPlay=20, players=None, playerSum=None)¶

A class to handle a season of tournaments being played.

A season is a squence of tournaments that are played by a group of players one after another and collect points as they go based on performance in each tournament.

Notes

At this points the seasons automatically use tournament and does not work with robin

Parameters

numPlayers (int, default 16) – The number of players that will be generated to play in this season. This will be overridden if players are provided
tournToPlay (int, default 20) – The number of tournaments that this season will have,
players (list of players, default None) – Optional. If there are pre-existing players that the user wishes to enter into this season. The number of players in the list will override numPlayers.
playerSum (DataFrame, default None) – Optional. If the player are being provided externally then their summary data table can be provided for their total point record to be appended to.

week¶

An integer to keep track of what week (tournament) is being played out.

Type: int

tournRecs¶

A list that stores the results from each tournament.

Type: list of DataFrames

seasonRes¶

A pandas dataframe with all of the tournament results concatenated into one dataframe, which is done upon season completion.

Type: Dataframe, default None

export(fldr='seasonData')¶

A function to export the players, the tournament results tables, and the season points table as CSVs.

Parameters: fldr (str, default 'seasonData') – The name to call the folder the results shall be stored in.

gatherPoints()¶: A method to gather the total points of players aftern a tournament has been completed. These are store it in the playerSum.

playSeason()¶

A method to play out the season of tournaments.

This method will play all of the tournaments in order, storing tournament results, recording players total points and shuffling the order of players inbetween each tournament.

reset()¶

A method to reset the season.

It won’t reset the players but resets the week count and the tournament results record.

class synthSportPlayer.liveSeason(numPlayers=16, tournToPlay=20, players=None, playerSum=None)¶

Bases: synthSportPlayer.sportplayer.season

A class to facilitate live dashboarding of a season/tournament being played

For further info see the parent class season.

currentTourn¶

The current tournament that is in progress

Type: liveTourn

currentTournComplete¶

A boolean indicating if the current tournament is completed or not.

Type: bool

playSeason()¶

A method to play the season.

Unlike it’s parent class, when this method is called it will only play the next round of the tournament. But if the tournament is complete it will update the records and move onto make the next tournament and play the first round.

Returns: complete – A boolean indicating if the season is completed or not.
Return type: bool

Ultilities¶

These functions are ultility functions designed to help with any analysis to be done.

synthSportPlayer.generatePlayers(number, maxSkill=100, var=10)¶

A function to generate a numbers of players.

This will generate the given number of players whose skill is uniformly random between 1 and maxSkill, and whose variance is equal to var.

Parameters

number (int) – The number of players that are to be created.
maxSkill (int or float, default 100) – The max skill that a player can have.
var (int or float, default 10) – The variance to give to each player.

Returns

playerList (list of players) – A list containing the players created.
playerInfo (DataFrame) – A table with information about the players created.

synthSportPlayer.fetchPlayerSummary(playerList)¶

A function to generate a player summary table.

Given a list of players this will generate a pandas table with the players summary.

Parameters: playerList (list of player) – A list of players whose summary wants to be fetched
Returns: playerinfo – A data frame containg the summary information of all the players provided.
Return type: DataFrame

synthSportPlayer.getPlayerHist(pid, df)¶

A function to get all the matches of a given player that reside in the provided dataframe. Will work on individual tournament results or on concatenated season results.

Parameters

pid (str) – The name of the player whose match results are to be searched for. This should be the players ‘.name’ atrribute
df (DataFrame) – The DataFrame that contains match results

Returns

pid_df – A DataFrame that contains match results that the given player has participated in.

Return type

DataFrame

synthSportPlayer.getMatchUpData(pid1, pid2, df)¶

A function to get all the matches between two players that reside in the provided dataframe. Will work on individual tournament results or on concatenated season results.

Parameters

pid1 (str) – The name of a player whose match results are to be searched for. This should be the players ‘.name’ atrribute
pid2 (str) – The name of the other player whose match results are to be searched for. This should be the players ‘.name’ atrribute
df (DataFrame) – The DataFrame that contains match results

Returns

mu_df – A DataFrame that contains match results that the two player has participated in against each other.

Return type

DataFrame