Datasets

It provides the tools to extract sports betting data.

DummySoccerDataLoader(param_grid=None)

Bases: _BaseDataLoader

Dataloader for soccer dummy data.

The data are provided only for convenience, since they require no downloading, and to familiarize the user with the methods of the dataloader objects.

Read more in the user guide.

Parameters:

Name	Type	Description	Default
param_grid	ParamGrid | None	It selects the type of information that the data include. The keys of dictionaries might be parameters like 'league' or 'division' while the values are sequences of allowed values. It works in a similar way as the param_grid parameter of the scikit-learn's ParameterGrid class. The default value None corresponds to all parameters.	None

Attributes:

Name	Type	Description
param_grid_	ParameterGrid	The checked value of parameters grid. It includes all possible parameters if param_grid is None.
dropped_na_cols_	Index	The columns with missing values that are dropped.
drop_na_thres_(float)	Index	The checked value of drop_na_thres.
odds_type_	str | None	The checked value of odds_type.
input_cols_	Index	The columns of X_train and X_fix.
output_cols_	Index	The columns of Y_train and Y_fix.
odds_cols_	Index	The columns of O_train and O_fix.
target_cols_	Index	The columns used for the extraction of output and odds columns.
train_data_	TrainData	The tuple (X, Y, O) that represents the training data as extracted from the method extract_train_data.
fixtures_data_	FixturesData	The tuple (X, Y, O) that represents the fixtures data as extracted from the method extract_fixtures_data.

Examples:

>>> from sportsbet.datasets import DummySoccerDataLoader
>>> import pandas as pd
>>> # Get all available parameters to select the training data
>>> DummySoccerDataLoader.get_all_params()
[{'division': 1, 'year': 1998}, ...
>>> # Select only the traning data for the Spanish league
>>> dataloader = DummySoccerDataLoader(param_grid={'league': ['Spain']})
>>> # Get available odds types
>>> dataloader.get_odds_types()
['interwetten', 'williamhill']
>>> # Select the odds of Interwetten bookmaker for training data
>>> X_train, Y_train, O_train = dataloader.extract_train_data(
... odds_type='interwetten')
>>> # Extract the corresponding fixtures data
>>> X_fix, Y_fix, O_fix = dataloader.extract_fixtures_data()
>>> # Training and fixtures input and odds data have the same column names
>>> pd.testing.assert_index_equal(X_train.columns, X_fix.columns)
>>> pd.testing.assert_index_equal(O_train.columns, O_fix.columns)
>>> # Fixtures data have always no output
>>> Y_fix is None
True

Source code in src/sportsbet/datasets/_dummy.py

def __init__(self: Self, param_grid: ParamGrid | None = None) -> None:
    super().__init__(param_grid)

extract_fixtures_data()

Extract the fixtures data.

Read more in the user guide.

It returns fixtures data that can be used to make predictions for upcoming matches based on a betting strategy.

Before calling the extract_fixtures_data method for the first time, the extract_training_data should be called, in order to match the columns of the input, output and odds data.

The data contain information about the matches known before the start of the match, i.e. the training data X and the odds data O. The multi-output targets Y is always equal to None and are only included for consistency with the method extract_train_data.

The param_grid parameter of the initialization method has no effect on the fixtures data.

Returns:

Type	Description
(X, None, O)	Each of the components represent the fixtures input data X, the multi-output targets Y equal to None and the corresponding odds O, respectively.

Source code in src/sportsbet/datasets/_dummy.py

def extract_fixtures_data(self: Self) -> FixturesData:
    """Extract the fixtures data.

    Read more in the [user guide][dataloader].

    It returns fixtures data that can be used to make predictions for
    upcoming matches based on a betting strategy.

    Before calling the `extract_fixtures_data` method for
    the first time, the `extract_training_data` should be called, in
    order to match the columns of the input, output and odds data.

    The data contain information about the matches known before the
    start of the match, i.e. the training data `X` and the odds
    data `O`. The multi-output targets `Y` is always equal to `None`
    and are only included for consistency with the method `extract_train_data`.

    The `param_grid` parameter of the initialization method has no effect
    on the fixtures data.

    Returns:
        (X, None, O):
            Each of the components represent the fixtures input data `X`, the
            multi-output targets `Y` equal to `None` and the
            corresponding odds `O`, respectively.
    """
    return super().extract_fixtures_data()

extract_train_data(drop_na_thres=0.0, odds_type=None)

Extract the training data.

Read more in the user guide.

It returns historical data that can be used to create a betting strategy based on heuristics or machine learning models.

The data contain information about the matches that belong in two categories. The first category includes any information known before the start of the match, i.e. the training data X and the odds data O. The second category includes the outcomes of matches i.e. the multi-output targets Y.

The method selects only the the data allowed by the param_grid parameter of the initialization method. Additionally, columns with missing values are dropped through the drop_na_thres parameter, while the types of odds returned is defined by the odds_type parameter.

Parameters:

Name	Type	Description	Default
drop_na_thres	float	The threshold that specifies the input columns to drop. It is a float in the [0.0, 1.0] range. Higher values result in dropping more values. The default value drop_na_thres=0.0 keeps all columns while the maximum value drop_na_thres=1.0 keeps only columns with non missing values.	0.0
odds_type	str | None	The selected odds type. It should be one of the available odds columns prefixes returned by the method get_odds_types. If odds_type=None then no odds are returned.	None

Returns:

Type	Description
(X, Y, O)	Each of the components represent the training input data X, the multi-output targets Y and the corresponding odds O, respectively.

Source code in src/sportsbet/datasets/_dummy.py

def extract_train_data(
    self: Self,
    drop_na_thres: float = 0.0,
    odds_type: str | None = None,
) -> TrainData:
    """Extract the training data.

    Read more in the [user guide][dataloader].

    It returns historical data that can be used to create a betting
    strategy based on heuristics or machine learning models.

    The data contain information about the matches that belong
    in two categories. The first category includes any information
    known before the start of the match, i.e. the training data `X`
    and the odds data `O`. The second category includes the outcomes of
    matches i.e. the multi-output targets `Y`.

    The method selects only the the data allowed by the `param_grid`
    parameter of the initialization method. Additionally, columns with missing
    values are dropped through the `drop_na_thres` parameter, while the
    types of odds returned is defined by the `odds_type` parameter.

    Args:
        drop_na_thres:
            The threshold that specifies the input columns to drop. It is a float in
            the `[0.0, 1.0]` range. Higher values result in dropping more values.
            The default value `drop_na_thres=0.0` keeps all columns while the
            maximum value `drop_na_thres=1.0` keeps only columns with non
            missing values.

        odds_type:
            The selected odds type. It should be one of the available odds columns
            prefixes returned by the method `get_odds_types`. If `odds_type=None`
            then no odds are returned.

    Returns:
        (X, Y, O):
            Each of the components represent the training input data `X`, the
            multi-output targets `Y` and the corresponding odds `O`, respectively.
    """
    return super().extract_train_data(drop_na_thres, odds_type)

SoccerDataLoader(param_grid=None)

Bases: _BaseDataLoader

Dataloader for soccer data.

It downloads historical and fixtures data for various leagues, years and divisions.

Read more in the user guide.

Parameters:

Name	Type	Description	Default
param_grid	ParamGrid | None	It selects the type of information that the data include. The keys of dictionaries might be parameters like 'league' or 'division' while the values are sequences of allowed values. It works in a similar way as the param_grid parameter of the scikit-learn's ParameterGrid class. The default value None corresponds to all parameters.	None

Attributes:

Name	Type	Description
param_grid_	ParameterGrid	The checked value of parameters grid. It includes all possible parameters if param_grid is None.
dropped_na_cols_	Index	The columns with missing values that are dropped.
drop_na_thres_(float)	Index	The checked value of drop_na_thres.
odds_type_	str | None	The checked value of odds_type.
input_cols_	Index	The columns of X_train and X_fix.
output_cols_	Index	The columns of Y_train and Y_fix.
odds_cols_	Index	The columns of O_train and O_fix.
target_cols_	Index	The columns used for the extraction of output and odds columns.
train_data_	TrainData	The tuple (X, Y, O) that represents the training data as extracted from the method extract_train_data.
fixtures_data_	FixturesData	The tuple (X, Y, O) that represents the fixtures data as extracted from the method extract_fixtures_data.

Examples:

>>> from sportsbet.datasets import SoccerDataLoader
>>> import pandas as pd
>>> # Get all available parameters to select the training data
>>> SoccerDataLoader.get_all_params()
[{'division': 1, 'league': 'Argentina', ...
>>> # Select only the traning data for the French and Spanish leagues of 2020 year
>>> dataloader = SoccerDataLoader(
... param_grid={'league': ['England', 'Spain'], 'year':[2020]})
>>> # Get available odds types
>>> dataloader.get_odds_types()
['market_average', 'market_maximum']
>>> # Select the market average odds and drop colums with missing values
>>> X_train, Y_train, O_train = dataloader.extract_train_data(
... odds_type='market_average')
>>> # Odds data include the selected market average odds
>>> O_train.columns
Index(['odds__market_average__home_win__full_time_goals',...
>>> # Extract the corresponding fixtures data
>>> X_fix, Y_fix, O_fix = dataloader.extract_fixtures_data()
>>> # Training and fixtures input and odds data have the same column names
>>> pd.testing.assert_index_equal(X_train.columns, X_fix.columns)
>>> pd.testing.assert_index_equal(O_train.columns, O_fix.columns)
>>> # Fixtures data have always no output
>>> Y_fix is None
True

Source code in src/sportsbet/datasets/_soccer/_data.py

def __init__(self: Self, param_grid: ParamGrid | None = None) -> None:
    super().__init__(param_grid)

extract_fixtures_data()

Extract the fixtures data.

Read more in the user guide.

It returns fixtures data that can be used to make predictions for upcoming matches based on a betting strategy.

Before calling the extract_fixtures_data method for the first time, the extract_training_data should be called, in order to match the columns of the input, output and odds data.

The data contain information about the matches known before the start of the match, i.e. the training data X and the odds data O. The multi-output targets Y is always equal to None and are only included for consistency with the method extract_train_data.

The param_grid parameter of the initialization method has no effect on the fixtures data.

Returns:

Type	Description
(X, None, O)	Each of the components represent the fixtures input data X, the multi-output targets Y equal to None and the corresponding odds O, respectively.

Source code in src/sportsbet/datasets/_soccer/_data.py

def extract_fixtures_data(self: Self) -> FixturesData:
    """Extract the fixtures data.

    Read more in the [user guide][dataloader].

    It returns fixtures data that can be used to make predictions for
    upcoming matches based on a betting strategy.

    Before calling the `extract_fixtures_data` method for
    the first time, the `extract_training_data` should be called, in
    order to match the columns of the input, output and odds data.

    The data contain information about the matches known before the
    start of the match, i.e. the training data `X` and the odds
    data `O`. The multi-output targets `Y` is always equal to `None`
    and are only included for consistency with the method `extract_train_data`.

    The `param_grid` parameter of the initialization method has no effect
    on the fixtures data.

    Returns:
        (X, None, O):
            Each of the components represent the fixtures input data `X`, the
            multi-output targets `Y` equal to `None` and the
            corresponding odds `O`, respectively.
    """
    return super().extract_fixtures_data()

extract_train_data(drop_na_thres=0.0, odds_type=None)

Extract the training data.

Read more in the user guide.

It returns historical data that can be used to create a betting strategy based on heuristics or machine learning models.

The data contain information about the matches that belong in two categories. The first category includes any information known before the start of the match, i.e. the training data X and the odds data O. The second category includes the outcomes of matches i.e. the multi-output targets Y.

The method selects only the the data allowed by the param_grid parameter of the initialization method. Additionally, columns with missing values are dropped through the drop_na_thres parameter, while the types of odds returned is defined by the odds_type parameter.

Parameters:

Name	Type	Description	Default
drop_na_thres	float	The threshold that specifies the input columns to drop. It is a float in the [0.0, 1.0] range. Higher values result in dropping more values. The default value drop_na_thres=0.0 keeps all columns while the maximum value drop_na_thres=1.0 keeps only columns with non missing values.	0.0
odds_type	str | None	The selected odds type. It should be one of the available odds columns prefixes returned by the method get_odds_types. If odds_type=None then no odds are returned.	None

Returns:

Type	Description
(X, Y, O)	Each of the components represent the training input data X, the multi-output targets Y and the corresponding odds O, respectively.

Source code in src/sportsbet/datasets/_soccer/_data.py

def extract_train_data(
    self: Self,
    drop_na_thres: float = 0.0,
    odds_type: str | None = None,
) -> TrainData:
    """Extract the training data.

    Read more in the [user guide][dataloader].

    It returns historical data that can be used to create a betting
    strategy based on heuristics or machine learning models.

    The data contain information about the matches that belong
    in two categories. The first category includes any information
    known before the start of the match, i.e. the training data `X`
    and the odds data `O`. The second category includes the outcomes of
    matches i.e. the multi-output targets `Y`.

    The method selects only the the data allowed by the `param_grid`
    parameter of the initialization method. Additionally, columns with missing
    values are dropped through the `drop_na_thres` parameter, while the
    types of odds returned is defined by the `odds_type` parameter.

    Args:
        drop_na_thres:
            The threshold that specifies the input columns to drop. It is a float in
            the `[0.0, 1.0]` range. Higher values result in dropping more values.
            The default value `drop_na_thres=0.0` keeps all columns while the
            maximum value `drop_na_thres=1.0` keeps only columns with non
            missing values.

        odds_type:
            The selected odds type. It should be one of the available odds columns
            prefixes returned by the method `get_odds_types`. If `odds_type=None`
            then no odds are returned.

    Returns:
        (X, Y, O):
            Each of the components represent the training input data `X`, the
            multi-output targets `Y` and the corresponding odds `O`, respectively.
    """
    return super().extract_train_data(drop_na_thres=drop_na_thres, odds_type=odds_type)

load_dataloader(path)

Load the dataloader object.

Parameters:

Name	Type	Description	Default
path	str	The path of the dataloader pickled file.	required

Returns:

Name	Type	Description
dataloader	_BaseDataLoader	The dataloader object.

Source code in src/sportsbet/datasets/_base.py

def load_dataloader(path: str) -> _BaseDataLoader:
    """Load the dataloader object.

    Args:
        path:
            The path of the dataloader pickled file.

    Returns:
        dataloader:
            The dataloader object.
    """
    with Path(path).open('rb') as file:
        dataloader = cloudpickle.load(file)
    return dataloader