API Documentation¶

Generic Environments¶

Environment that are agnostic to the sport game of chance.

BaseOddsEnv¶

class oddsgym.envs.base.BaseOddsEnv(odds, odds_column_names, results=None, starting_bank=300, render_mode=None)¶

Base class for sports betting environments.

Creates an OpenAI Gym environment that supports betting a fixed amount (1) on a single outcome for a single game.

Added in version 0.1.0.

Parameters:

observation_space (gym.spaces.Box) – The observation space for the environment. The observation space shape is (1, N) where N is the number of possible outcomes for the game.

Changed in version 0.3.0: Changed definition of space
action_space (gym.spaces.Discrete) – The action space for the environment. The action space is a single number in [0, 2 ** N), representing on what outcomes to place a bet by conversion to a binary representation.

Changed in version 0.3.0: Changed definition of space
balance (float) – The current balance of the environment.
starting_bank (int, default=10) – The starting bank / balance for the environment.

__init__(odds, odds_column_names, results=None, starting_bank=300, render_mode=None)¶

Initializes a new environment

Parameters:

odds (dataframe of shape (n_games, n_odds)) – A list of games, with their betting odds.
odds_column_names (list of str) – A list of column names with length == n_odds.
results (list of int, default=None) – A list of the results, where results[i] is the outcome of odds[i].

create_info(action)¶

Creates the info dictionary for the given action.

The info dictionary holds the following information:

the verbose action
the current step
the balance at the start of the current step
the relevant odds for the current step
the bet size for a single outcome

Parameters:: action (int) – An action provided by the agent.
Returns:: info (dict) – The info dictionary.

finish()¶

Checks if the episode has reached an end.

The episode has reached an end if there are no more games to bet.

Returns:: finish (bool) – True if the current_step is equal to n_games, False otherwise

get_bet(action)¶

Returns the betting matrix for the action provided.

Parameters:: action (int) – An action provided by the agent.
Returns:: bet (array of shape (1, n_odds)) – The betting matrix, where each outcome specified in the action has a value of 1 and 0 otherwise.

get_odds()¶

Returns the odds for the current step.

Returns:: odds (numpy.ndarray of shape (1, n_odds)) – The odds for the current step.

get_results()¶

Returns the results matrix for the current step.

Returns:: result (array of shape (1, n_odds)) – The result matrix, where the index of the outcome that happened value is 1 and the rest of the indexes values are 0.

get_reward(bet, odds, results)¶

Calculates the reward

Parameters:

bet (array of shape (1, n_odds))
odds (dataframe of shape (1, n_odds)) – A games with its betting odds.
results (array of shape (1, n_odds))

Returns:

reward (float) – The amount of reward returned after previous action

legal_bet(bet)¶

Checks if the bet is legal.

Checks that the bet does not exceed the current balance.

Parameters:: bet (array of shape (1, n_odds)) – The bet to check.
Returns:: legal (bool) – True if the bet is legal, False otherwise.

render()¶

Outputs the current balance and the current step.

Returns:: msg (str) – A string with the current balance and the current step.

reset(*, seed=None, options=None)¶

Resets the state of the environment and returns an initial observation.

Returns:: observation (dataframe of shape (1, n_odds)) – the initial observation.

step(action)¶

Run one timestep of the environment’s dynamics. When end of episode is reached, you are responsible for calling reset() to reset this environment’s state.

Accepts an action and returns a tuple (observation, reward, done, info).

Parameters:

action (int) – An action provided by the agent.

Returns:

observation (dataframe of shape (1, n_odds)) – The agent’s observation of the current environment
reward (float) – The amount of reward returned after previous action
done (bool) – Whether the episode has ended, in which case further step() calls will return undefined results
info (dict) – Contains auxiliary diagnostic information (helpful for debugging, and sometimes learning)

BasePercentageOddsEnv¶

class oddsgym.envs.base_percentage.BasePercentageOddsEnv(odds, odds_column_names, results=None, *args, **kwargs)¶

Base class for sports betting environments with non fixed bet size.

Creates an OpenAI Gym environment that supports betting a non fixed amount on a single outcome for a single game.

The main difference between the BaseOddsEnv is that the action space is defined differently (to accommodate that non fixed bet size).

Added in version 0.2.0.

Changed in version 0.4.5: Name changed to “BasePercentageOddsEnv”

Parameters:

action_space (gym.spaces.Box of shape (N,), where N is the number of possible) – outcomes for the game. The indexes are the percentage of the current balance to place on matching outcome, so that action[i] is the bet percentage for outcome[i].

Changed in version 0.5.0: Change action space so that each outcome has it’s own independent bet percentage.

Changed in version 0.6.0: Change action space bounds to [-1, 1] and rescale the action back inside the step method.

Changed in version 0.7.0: Reduce dimesionality of action space, deduce the action implicitly from the given percentages

The rescaling an action \((a, p_0, ..., p_{N-1})\in\text{action_space}, -1 \leq a, p_0, ..., p_{N-1} \leq 1\):

\[\begin{split}\begin{cases} a' = \lfloor (a + 1) * (2^{N-1}) \rfloor\\ p_i' = |p_i| \end{cases}\end{split}\]

DailyOddsEnv¶

class oddsgym.envs.daily_bets.DailyOddsEnv(odds, odds_column_names, results=None, max_number_of_games='auto', *args, **kwargs)¶

Base class for sports betting environments multiple games with a fixed bet size.

Creates an OpenAI Gym environment that supports betting a fixed amount (1) on a single outcome but for multiple games.

Added in version 0.3.0.

Parameters:

observation_space (gym.spaces.Box) – The observation space for the environment. The observation space shape is (M, N) where M is the maximum number of games in a single day and N is the number of possible outcomes for the game.
action_space (gym.spaces.Box) – The action space for the environment. The action space shape is (M,), a list of numbers in [0, 2 ** N), representing on what outcomes to place a bet by conversion to a binary representation, where actions[i] is the action for odds[i].

Changed in version 0.6.0: Change action space bounds to [-1, 1] and rescale the action back inside the step method. For explanation on how the rescaling works, see BasePercentageOddsEnv
balance (float) – The current balance of the environment.
starting_bank (int, default=10) – The starting bank / balance for the environment.
days (array, dtype=np.datetime64) – Sorted array of the days.

DailyPercentageOddsEnv¶

class oddsgym.envs.daily_bets.DailyPercentageOddsEnv(odds, odds_column_names, results=None, *args, **kwargs)¶

Base class for sports betting environments multiple games with a non fixed bet size.

Creates an OpenAI Gym environment that supports betting a non fixed amount on a single outcome but for multiple games.

Added in version 0.5.0.

Parameters:

action_space (gym.spaces.Box of shape (n_games * n_odds,)) – A vector with the action and the percentage for each outcome, so that:

\[\begin{split}a[i] = \begin{cases} \text{the action} & i\mod\text{(n_odds + 1)}\equiv 0\\ \text{percentage of outcome j} & i\mod\text{(n_odds + 1)}\equiv j \end{cases}\end{split}\]

For the game \(\lfloor \frac{i}{\text{n_games}} \rfloor\).

Changed in version 0.6.0: Change action space bounds to [-1, 1] and rescale the action back inside the step method. For explanation on how the rescaling works, see BasePercentageOddsEnv

Changed in version 0.7.0: Reduce dimesionality of action space by deducing action from betting percentages

Sports Specific Environments¶

Environment that are sport specific.

ThreeWaySoccerOddsEnv¶

class oddsgym.envs.soccer.ThreeWaySoccerOddsEnv(soccer_bets_dataframe, *args, **kwargs)¶

Environment for 3-way soccer betting with a fixed bet size.

Added in version 0.1.0.

__init__(soccer_bets_dataframe, *args, **kwargs)¶

Initializes a new environment.

Parameters:: soccer_bets_dataframe (dataframe of shape (n_games, n_odds + 3), n_odds == 3) – A list of games, with their betting odds, results and the teams playing.

Warning

Please make sure that the odds columns are named “home, draw, away”, that the results column is named “result” and that the team names columns are named “home_team, away_team” respectively.

ThreeWaySoccerPercentageOddsEnv¶

class oddsgym.envs.soccer.ThreeWaySoccerPercentageOddsEnv(soccer_bets_dataframe, *args, **kwargs)¶: Environment for 3-way soccer betting with a non fixed bet size.

Added in version 0.2.0.

ThreeWaySoccerDailyOddsEnv¶

class oddsgym.envs.soccer.ThreeWaySoccerDailyOddsEnv(soccer_bets_dataframe, *args, **kwargs)¶: Environment for 3-way soccer betting, grouped by date, with a fixed bet size.

Added in version 0.5.0.

ThreeWaySoccerDailyPercentageOddsEnv¶

class oddsgym.envs.soccer.ThreeWaySoccerDailyPercentageOddsEnv(soccer_bets_dataframe, *args, **kwargs)¶: Environment for 3-way soccer betting, grouped by date, with a non fixed bet size.

Added in version 0.5.0.

TennisOddsEnv¶

class oddsgym.envs.tennis.TennisOddsEnv(tennis_bets_dataframe, *args, **kwargs)¶

Environment for tennis betting with a fixed bet size.

Added in version 0.8.0.

__init__(tennis_bets_dataframe, *args, **kwargs)¶

Initializes a new environment.

Parameters:: tennis_bets_dataframe (dataframe of shape (n_matches, n_odds + 3), n_odds == 2) – A list of matches, with their betting odds, results and the players playing.

Warning

Please make sure that the odds columns are named “win, lose”, that the results column is named “result” and that the player names columns are named “winner, loser” respectively.

TennisPercentageOddsEnv¶

class oddsgym.envs.tennis.TennisPercentageOddsEnv(tennis_bets_dataframe, *args, **kwargs)¶: Environment for tennis betting with a non fixed bet size.

Added in version 0.8.0.

TennisDailyOddsEnv¶

class oddsgym.envs.tennis.TennisDailyOddsEnv(tennis_bets_dataframe, *args, **kwargs)¶: Environment for tennis betting, grouped by date, with a fixed bet size.

Added in version 0.8.0.

TennisDailyPercentageOddsEnv¶

class oddsgym.envs.tennis.TennisDailyPercentageOddsEnv(tennis_bets_dataframe, *args, **kwargs)¶: Environment for tennis betting, grouped by date, with a non fixed bet size.

Added in version 0.8.0.

Site and Sports Specific Environments¶

Environment that are site and sport specific (receives the odds data from a specific site).

FootballDataDailyEnv¶

class oddsgym.envs.footballdata.FootballDataDailyEnv(config=None, *args, **kwargs)¶

Environment for 3-way soccer, with odds from www.football-data.co.uk betting, grouped by date, with a fixed bet size.

Added in version 0.7.1.

__init__(config=None, *args, **kwargs)¶

Initializes a new environment

Parameters:

country (str, defaults to “England”) – The name of the country in which the league is playing.
league (str, defaults to “Premier League”) – The name of the league.
start (int, defaults to 2010) – Start year of the league to use.
end (int, defaults to 2011) – End year of the league to use.
columns ({“max”, “avg”}, defaults to “max”) – Which columns to use for the odds data. “max” uses the maximum value for each odd from all sites, “avg” uses the average value.
extra (bool, default to False) – Use extra odds for the observation space.
optimize ({“balance”, “reward”}, default to “balance”) – Which type of optimization to use.

FootballDataDailyPercentageEnv¶

class oddsgym.envs.footballdata.FootballDataDailyPercentageEnv(config=None, *args, **kwargs)¶: Environment for 3-way soccer, with odds from www.football-data.co.uk betting, grouped by date, with a non fixed bet size.

Added in version 0.6.2.

TennisDataDailyEnv¶

class oddsgym.envs.tennisdata.TennisDataDailyEnv(config=None, *args, **kwargs)¶

Environment for Tennis, with odds from www.tennis-data.co.uk betting, grouped by date, with a fixed bet size.

Added in version 0.8.0.

__init__(config=None, *args, **kwargs)¶

Initializes a new environment

Parameters:

tournament (str, defaults to “ausopen”) – The name of the tournament.
year (int, defaults to 2010) – Year of the tournament.
columns ({“max”, “avg”}, defaults to “max”) – Which columns to use for the odds data. “max” uses the maximum value for each odd from all sites, “avg” uses the average value.
extra (bool, default to False) – Use extra odds for the observation space.
optimize ({“balance”, “reward”}, default to “balance”) – Which type of optimization to use.

TennisDataDailyPercentageEnv¶

class oddsgym.envs.tennisdata.TennisDataDailyPercentageEnv(config=None, *args, **kwargs)¶: Environment for Tennis, with odds from www.tennis-data.co.uk betting, grouped by date, with a non fixed bet size.

Added in version 0.8.0.