Sports Betting

https://georgedouzas.github.io/sports-betting
Admin
Sports Betting is a Python package that provides tools for downloading sports betting data, creating...
Tokens:32,169
Snippets:295
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example Data Extraction

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide/dataloader

Provides an example of initializing the DataLoader and extracting both training and fixtures data with specific parameters.

```python
from sportsbet.datasets import SoccerDataLoader
param_grid = {'league': ['England'], 'year': [2021]}
dataloader = SoccerDataLoader(param_grid=param_grid)
X_train, Y_train, O_train = dataloader.extract_train_data(odds_type='market_maximum')
X_fix, Y_fix, O_fix = dataloader.extract_fixtures_data()
```

--------------------------------

### Install Project Dependencies with PDM

Source: https://georgedouzas.github.io/sports-betting/development

Run this command from the root of the project after installing PDM and cloning the repository to install all necessary main and development dependencies.

```bash
pdm install
```

--------------------------------

### SoccerDataLoader Usage Example

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Demonstrates how to use SoccerDataLoader to fetch and process soccer data. Includes examples for getting all parameters, selecting specific data, extracting training and fixture data with different odds types, and verifying data consistency.

```python
>>> 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
```

--------------------------------

### Install sports-betting Package

Source: https://georgedouzas.github.io/sports-betting

Installs the sports-betting package using pip. For optional GUI support, use the '[gui]' extra.

```bash
pip install sports_betting

```

```bash
pip install sports_betting[gui]

```

--------------------------------

### Development Installation of sports-betting

Source: https://georgedouzas.github.io/sports-betting

Installs the sports-betting package for development using PDM after cloning the repository. Includes main and development dependencies.

```bash
git clone https://github.com/georgedouzas/sports-betting.git
cd sports-betting
pdm install

```

--------------------------------

### Initialize SoccerDataLoader with Parameters

Source: https://georgedouzas.github.io/sports-betting/generated/gallery/plot_soccer_data.ipynb

Instantiate the SoccerDataLoader by providing a dictionary of parameters to filter the data. This example selects data for Spain and Italy in division 1 for the year 2021.

```python
param_grid = {'league': ['Spain', 'Italy'], 'division': [1], 'year': [2021]}
dataloader = SoccerDataLoader(param_grid=param_grid)
```

--------------------------------

### Get All Parameters for DummySoccerDataLoader

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide/dataloader

Retrieves all available parameters for the DummySoccerDataLoader. This is useful for understanding the data available for testing.

```python
from sportsbet.datasets import DummySoccerDataLoader
assert DummySoccerDataLoader.get_all_params() == [
    {'division': 1, 'year': 1998},
    {'division': 1, 'league': 'France', 'year': 2000},
    {'division': 1, 'league': 'France', 'year': 2001},
    {'division': 1, 'league': 'Greece', 'year': 2017},
    {'division': 1, 'league': 'Greece', 'year': 2019},
    {'division': 1, 'league': 'Spain', 'year': 1997},
    {'division': 2, 'league': 'England', 'year': 1997},
    {'division': 2, 'league': 'Spain', 'year': 1999},
    {'division': 3, 'league': 'England', 'year': 1998}
]
```

--------------------------------

### DummySoccerDataLoader Methods

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Demonstrates how to use DummySoccerDataLoader to retrieve and process soccer data, including getting all parameters, available odds types, and extracting training and fixtures data.

```APIDOC
## DummySoccerDataLoader Usage Examples

### Description
Examples demonstrating the usage of the DummySoccerDataLoader class to access and process soccer data.

### Methods

#### `get_all_params()`

**Description**: Retrieves all available parameters for selecting training data.

**Example**:
```python
>>> from sportsbet.datasets import DummySoccerDataLoader
>>> DummySoccerDataLoader.get_all_params()
[{'division': 1, 'year': 1998}, ...]
```

#### `get_odds_types()`

**Description**: Retrieves the available odds types for the data.

**Example**:
```python
>>> dataloader = DummySoccerDataLoader(param_grid={'league': ['Spain']})
>>> dataloader.get_odds_types()
['interwetten', 'williamhill']
```

#### `extract_train_data(odds_type)`

**Description**: Extracts training data (X, Y, O) for a specified odds type.

**Parameters**:
- **odds_type** (str) - The type of odds to extract.

**Example**:
```python
>>> X_train, Y_train, O_train = dataloader.extract_train_data(odds_type='interwetten')
```

#### `extract_fixtures_data()`

**Description**: Extracts fixtures data (X, Y, O).

**Example**:
```python
>>> X_fix, Y_fix, O_fix = dataloader.extract_fixtures_data()
```

### Assertions

**Description**: Verifies that training and fixtures input and odds data have consistent column names, and that fixtures data have no output.

**Example**:
```python
>>> import pandas as pd
>>> pd.testing.assert_index_equal(X_train.columns, X_fix.columns)
>>> pd.testing.assert_index_equal(O_train.columns, O_fix.columns)
>>> Y_fix is None
True
```
```

--------------------------------

### Initialize Classifier Bettor with Dummy Classifier

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide/bettor

Initializes the ClassifierBettor using scikit-learn's DummyClassifier. This is a common setup for testing and demonstrating bettor functionalities.

```python
from sklearn.dummy import DummyClassifier
from sportsbet.evaluation import ClassifierBettor
bettor = ClassifierBettor(classifier=DummyClassifier())
```

--------------------------------

### Get All Parameters for SoccerDataLoader

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide/dataloader

Retrieves all available parameters for the SoccerDataLoader. This shows the range of leagues, divisions, and years for which data can be loaded.

```python
from sportsbet.datasets import SoccerDataLoader
assert SoccerDataLoader.get_all_params() == [
    {'division': 1, 'league': 'Argentina', 'year': 2018},
    {'division': 1, 'league': 'Argentina', 'year': 2019},
    {'division': 1, 'league': 'Argentina', 'year': 2020},
    ...,
    {'division': 5,  'league': 'England', 'year': 2022},
    {'division': 5, 'league': 'England', 'year': 2023},
    {'division': 5, 'league': 'England', 'year': 2024}
]
```

--------------------------------

### Backtest OddsComparisonBettor - Python

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Example of backtesting the OddsComparisonBettor strategy. It involves loading soccer data, extracting training data with specific odds types, and then using the backtest function.

```python
>>> from sportsbet.evaluation import OddsComparisonBettor, backtest
>>> from sportsbet.datasets import SoccerDataLoader
>>> # Select only backtesting data for the Italian and Spanish leagues and years 2019 - 2022
>>> param_grid = {'league': ['Italy', 'Spain'], 'year': [2019, 2020, 2021, 2022]}
>>> dataloader = SoccerDataLoader(param_grid)
>>> # Select the market maximum odds
>>> X, Y, O = dataloader.extract_train_data(
... odds_type='market_maximum',
... )
>>> # Backtest the bettor
>>> bettor = OddsComparisonBettor(alpha=0.03)
>>> backtest(bettor, X, Y, O).reset_index()
  Training start ... Yield percentage per bet (under_2.5__full_time_goals)
...
```

--------------------------------

### Backtesting and Predicting Value Bets with Python API

Source: https://georgedouzas.github.io/sports-betting

This snippet demonstrates how to configure data loading, set up a betting strategy using a logistic regression classifier, and perform backtesting or predict value bets using the Python API. Ensure necessary libraries like scikit-learn and sportsbet are installed.

```python
# Selection of data
from sportsbet.datasets import SoccerDataLoader

leagues = ['Germany', 'Italy', 'France']
divisions = [1, 2]
years = [2021, 2022, 2023, 2024]
odds_type = 'market_maximum'
dataloader = SoccerDataLoader({'league': leagues, 'year': years, 'division': divisions})
X_train, Y_train, O_train = dataloader.extract_train_data(odds_type=odds_type)
X_fix, _, O_fix = dataloader.extract_fixtures_data()

# Configuration of betting strategy
from sklearn.model_selection import TimeSeriesSplit
from sklearn.compose import make_column_transformer
from sklearn.linear_model import LogisticRegression
from sklearn.impute import SimpleImputer
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import OneHotEncoder
from sklearn.multioutput import MultiOutputClassifier
from sportsbet.evaluation import ClassifierBettor, backtest

tscv = TimeSeriesSplit(5)
init_cash = 10000.0
stake = 50.0
betting_markets = ['home_win__full_time_goals', 'draw__full_time_goals', 'away_win__full_time_goals']
classifier = make_pipeline(
  make_column_transformer(
    (OneHotEncoder(handle_unknown='ignore'), ['league', 'home_team', 'away_team']), remainder='passthrough'
  ),
  SimpleImputer(),
  MultiOutputClassifier(LogisticRegression(solver='liblinear', random_state=7, class_weight='balanced', C=50)),
)
bettor = ClassifierBettor(classifier, betting_markets=betting_markets, stake=stake, init_cash=init_cash)

# Apply backtesting and get results
backtesting_results = backtest(bettor, X_train, Y_train, O_train, cv=tscv)

# Get value bets for upcoming betting events
bettor.fit(X_train, Y_train)
bettor.bet(X_fix, O_fix)

```

--------------------------------

### Get All Parameters for DataLoader

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Retrieves a list of all available parameters and their values for the `param_grid` of a dataloader. Use this to understand the configurable options for data loading.

```python
@classmethod
def get_all_params(cls: type[BaseDataLoader]) -> list[Param]:
    """Get the available parameters.

    It can be used to get the allowed names and values for the
    `param_grid` parameter of the dataloader object.

    Returns:
        param_grid: list
            A list of all allowed params and values.
    """
    full_param_grid = cls._get_full_param_grid()
    params_names = sorted({param_name for params in full_param_grid for param_name in params})
    all_params = sorted(
        full_param_grid,
        key=lambda params: tuple(
            params.get(name, '' if dict(cls.SCHEMA)[name] is object else 0) for name in params_names
        ),
    )
    return all_params
```

--------------------------------

### CLI: Get value bets

Source: https://georgedouzas.github.io/sports-betting

Use this command to obtain value bets based on the configured bettor and save them as a CSV file. Specify the configuration file and the output directory.

```bash
sportsbet bettor bet -c config.py -d /path/to/directory

```

--------------------------------

### Get Available Parameters for SoccerDataLoader

Source: https://georgedouzas.github.io/sports-betting/generated/gallery/plot_soccer_data.ipynb

Use the get_all_params class method to retrieve a dictionary of all available parameters that can be used to filter the soccer data.

```python
SoccerDataLoader.get_all_params()
```

--------------------------------

### Commit Message Example

Source: https://georgedouzas.github.io/sports-betting/development/contributing

An example of a commit message following the Angular style convention. It includes type, scope, subject, a detailed body, and issue/PR references in the footer.

```markdown
feat(directive): A new feature of code

A description of the new feature.
It contains **important** information.

Issue #10: https://github.com/namespace/project/issues/10
Related to PR namespace/other-project#15: https://github.com/namespace/other-project/pull/15


```

--------------------------------

### Get Value Bets for Upcoming Events

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide

Fit the bettor with training data and then use it to predict value bets for upcoming betting events using fixtures data. This provides betting recommendations.

```python
bettor.fit(X_train[num_cols], Y_train)
value_bets = bettor.bet(X_fix[num_cols], O_fix)
```

--------------------------------

### Backtest BettorGridSearchCV with TimeSeriesSplit

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Performs a backtest using BettorGridSearchCV with a TimeSeriesSplit cross-validation strategy. This example demonstrates selecting data for specific leagues and years, extracting training data with market maximum odds, and then backtesting the optimized bettor.

```python
>>> from sportsbet.evaluation import BettorGridSearchCV, OddsComparisonBettor, backtest
>>> from sportsbet.datasets import SoccerDataLoader
>>> from sklearn.model_selection import TimeSeriesSplit
>>> # Select only backtesting data for the Italian and Spanish leagues and years 2019 - 2022
>>> param_grid = {'league': ['Italy', 'Spain'], 'year': [2019, 2020, 2021, 2022]}
>>> dataloader = SoccerDataLoader(param_grid)
>>> # Select the market maximum odds
>>> X, Y, O = dataloader.extract_train_data(
... odds_type='market_maximum',
... )
>>> # Backtest the bettor
>>> bettor = BettorGridSearchCV(
... estimator=OddsComparisonBettor(),
... param_grid={'alpha': [0.02, 0.05, 0.1, 0.2, 0.3]},
... cv=TimeSeriesSplit(2),
... )
>>> backtest(bettor, X, Y, O, cv=TimeSeriesSplit(2)).reset_index()
  Training start ... Yield percentage per bet (under_2.5__full_time_goals)
...
```

--------------------------------

### Serve Project Documentation

Source: https://georgedouzas.github.io/sports-betting/development/contributing

Use this command to serve the project documentation locally. It's useful for previewing changes after updating documentation or dependencies.

```bash
pdm docs serve
```

--------------------------------

### Build Project Documentation Locally

Source: https://georgedouzas.github.io/sports-betting/development/contributing

Build the project documentation locally. This command is useful for generating the documentation files without serving them.

```bash
pdm docs build
```

--------------------------------

### Get Available Odds Types

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide/dataloader

Retrieves a list of available odds types that can be used for the odds matrix.

```python
assert dataloader.get_odds_types() == ['market_average', 'market_maximum']
```

--------------------------------

### Download Sports Betting Data with SoccerDataLoader

Source: https://georgedouzas.github.io/sports-betting

Initializes SoccerDataLoader with a parameter grid and extracts training and fixtures data. Use 'market_maximum' for odds type.

```python
from sportsbet.datasets import SoccerDataLoader
dataloader = SoccerDataLoader(param_grid={'league': ['Italy'], 'year': [2020]})
X_train, Y_train, O_train = dataloader.extract_train_data(odds_type='market_maximum')
X_fix, Y_fix, O_fix = dataloader.extract_fixtures_data()

```

--------------------------------

### CLI: Show available dataloader parameters

Source: https://georgedouzas.github.io/sports-betting

Use this command to display the available parameters for dataloaders when using the CLI. A configuration file is required.

```bash
sportsbet dataloader params -c config.py

```

--------------------------------

### Get Available Odds Types

Source: https://georgedouzas.github.io/sports-betting/generated/gallery/plot_soccer_data.ipynb

Call the get_odds_types method on a SoccerDataLoader instance to see the types of odds data that can be extracted.

```python
dataloader.get_odds_types()
```

--------------------------------

### Initialize SoccerDataLoader

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Instantiate the SoccerDataLoader with an optional parameter grid to filter data. The default None value selects all parameters.

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

--------------------------------

### Initialize DummySoccerDataLoader

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Initializes the DummySoccerDataLoader with an optional parameter grid to select specific data. The param_grid works similarly to scikit-learn's ParameterGrid.

```python
>>> 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']})
```

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

--------------------------------

### DummySoccerDataLoader Initialization

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Initializes the DummySoccerDataLoader with an optional parameter grid to select specific data subsets.

```APIDOC
## DummySoccerDataLoader(param_grid=None)

### Description
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.

### Parameters
#### Path Parameters
- **param_grid** (ParamGrid | None) - Optional - 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.

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

--------------------------------

### Initialize SoccerDataLoader with Custom Parameter Grid

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide/dataloader

Initializes the SoccerDataLoader with a specific parameter grid to select training data. This allows for targeted data extraction based on league, division, and year.

```python
from sportsbet.datasets import SoccerDataLoader
param_grid = [
    {'division': [1], 'league': ['Spain', 'Italy'], 'year': [2018, 2019, 2020]},
    {'league': ['France'], 'year': [2020, 2021]} 
]
dataloader = SoccerDataLoader(param_grid=param_grid)
```

--------------------------------

### Backtest ClassifierBettor with Soccer Data

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Demonstrates how to use ClassifierBettor for backtesting with soccer data. It involves loading data, creating a preprocessing pipeline, initializing the bettor, and running the backtest. The output shows backtesting results including yield percentage.

```python
>>> from sklearn.tree import DecisionTreeClassifier
>>> from sklearn.preprocessing import OneHotEncoder
>>> from sklearn.impute import SimpleImputer
>>> from sklearn.pipeline import make_pipeline
>>> from sklearn.compose import make_column_transformer
>>> from sportsbet.evaluation import ClassifierBettor, backtest
>>> from sportsbet.datasets import SoccerDataLoader
>>> # Select only backtesting data for the Italian league and years 2020, 2021
>>> param_grid = {'league': ['Italy'], 'year': [2020, 2021]}
>>> dataloader = SoccerDataLoader(param_grid)
>>> # Select the odds of Pinnacle bookmaker
>>> X, Y, O = dataloader.extract_train_data(
... odds_type='market_average',
... drop_na_thres=1.0
... )
>>> # Create a pipeline to handle categorical features and missing values
>>> clf_pipeline = make_pipeline(
... make_column_transformer(
... (OneHotEncoder(handle_unknown='ignore'), ['league', 'home_team', 'away_team']),
... remainder='passthrough'
... ),
... SimpleImputer(),
... DecisionTreeClassifier(random_state=0)
... )
>>> # Backtest the bettor
>>> bettor = ClassifierBettor(clf_pipeline)
>>> backtest(bettor, X, Y, O).reset_index()
  Training start ... Yield percentage per bet (under_2.5__full_time_goals)
...
```

--------------------------------

### Get Available Odds Types

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Retrieves a sorted list of available odds types that can be extracted by the `extract_train_data` method. This is useful for understanding the different formats of odds data supported.

```python
def get_odds_types(self: Self) -> list[str]:
    """Get the available odds types.

    It can be used to get the allowed odds types of the dataloader's method
    `extract_train_data`.

    Returns:
        odds_types:
            A list of available odds types.
    """
    # Check param grid
    self._check_param_grid()

    # Validate the data
    data = self._validate_data()

    # Extract train data
    data = self._extract_train_data(data)

    # Drop columns with only missing values
    dropped_all_na_cols = data.columns.difference(data.dropna(axis=1, how='all').columns)

    return sorted({col.split('__')[1] for col in self._cols(data, 'odds') if col not in dropped_all_na_cols})
```

--------------------------------

### Format Code and Docstrings

Source: https://georgedouzas.github.io/sports-betting/development/contributing

Run this command to format both the code and docstrings according to project standards. This ensures code consistency across the project.

```bash
pdm formatting all
```

--------------------------------

### Compare Training and Fixtures Data Columns

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide/dataloader

Asserts that the column lists for the input and odds matrices are identical between training and fixtures data.

```python
assert X_train.columns.tolist() == X_fix.columns.tolist()
assert O_train.columns.tolist() == O_fix.columns.tolist()
```

--------------------------------

### extract_fixtures_data()

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Extracts fixtures data which includes information about upcoming matches known before they start. This data can be used for making predictions. It's recommended to call `extract_training_data` before the first call to `extract_fixtures_data` to ensure data consistency.

```APIDOC
## extract_fixtures_data()

### Description
Extract the fixtures data. It returns fixtures data that can be used to make predictions for upcoming matches based on a betting strategy. Before calling this method for the first time, `extract_training_data` should be called to match columns. The data contains information about matches known before the start, i.e., training data `X` and odds data `O`. The multi-output targets `Y` is always `None` for consistency.

### Returns
- **(X, None, O)** (tuple): A tuple containing fixtures input data `X`, multi-output targets `Y` (always None), and corresponding odds `O`.
```

--------------------------------

### Backtest Betting Strategy with ClassifierBettor

Source: https://georgedouzas.github.io/sports-betting

Initializes a ClassifierBettor with a DummyClassifier and performs a backtest using historical data. Requires training data (X_train, Y_train) and odds (O_train).

```python
from sportsbet.evaluation import ClassifierBettor, backtest
from sklearn.dummy import DummyClassifier
bettor = ClassifierBettor(DummyClassifier())
backtest(bettor, X_train, Y_train, O_train)

```

--------------------------------

### Initialize BettorGridSearchCV

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Initializes BettorGridSearchCV with an estimator, parameter grid, and cross-validation strategy. Use this to set up hyperparameter tuning for your betting models.

```python
def __init__(
    self: Self,
    estimator: BaseBettor,
    param_grid: dict | list,
    *,
    scoring: str | Callable | list | tuple | dict[str, Callable] | None = None,
    n_jobs: int | None = None,
    refit: bool | str | Callable = True,
    cv: TimeSeriesSplit = TSCV,
    verbose: int = 0,
    pre_dispatch: int | str = '2*n_jobs',
    error_score: str | float | int = np.nan,
    return_train_score: bool = False,
) -> None:
    GridSearchCV.__init__(
        self,
        estimator=estimator,
        param_grid=param_grid,
        scoring=scoring,
        n_jobs=n_jobs,
        refit=refit,
        cv=cv,
        verbose=verbose,
        pre_dispatch=pre_dispatch,
        error_score=error_score,
        return_train_score=return_train_score,
    )

```

--------------------------------

### Initialize SoccerDataLoader

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide

Initialize the SoccerDataLoader for specified leagues and years. This prepares the data extraction process.

```python
from sportsbet.datasets import SoccerDataLoader
dataloader = SoccerDataLoader(param_grid={'league': ['Italy', 'Spain'], 'year': [2023, 2024]})
```

--------------------------------

### Initialize DataLoader and Extract Training Data

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide/dataloader

Initializes the SoccerDataLoader and extracts training data with a specified odds type.

```python
from sportsbet.datasets import SoccerDataLoader
param_grid = [
    {'division': [1], 'league': ['Spain', 'Italy'], 'year': [2018, 2019, 2020]},
]
dataloader = SoccerDataLoader(param_grid=param_grid)
X_train, Y_train, O_train = dataloader.extract_train_data(odds_type='market_average')
```

--------------------------------

### Extract Training and Fixtures Data with DummySoccerDataLoader

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Extracts training and fixtures data using the DummySoccerDataLoader. Allows selection of odds types and verifies column name consistency between training and fixtures data. Fixtures data typically does not include an output.

```python
>>> # 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
```

--------------------------------

### `OddsComparisonBettor(odds_types=None, alpha=0.05, betting_markets=None, init_cash=None, stake=None)`

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Initializes a Bettor based on the comparison of odds. This bettor implements a strategy based on predicted probabilities derived from average odds.

```APIDOC
## `OddsComparisonBettor` Constructor

### Description
Initializes a Bettor based on the comparison of odds. This bettor implements a strategy based on predicted probabilities derived from average odds.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **odds_types** (list[str] | None) - Optional - The odds types to use for the calculation of consensus probabilities. Defaults to 'market_average' or the average of all other odds columns if 'market_average' is missing.
- **alpha** (float) - Optional - An adjustment term that corresponds to the difference between the consensus and real probabilities. Defaults to 0.05.
- **betting_markets** (list[str] | None) - Optional - Select the betting markets from the ones included in the data.
- **init_cash** (float | None) - Optional - The initial cash to use when betting.
- **stake** (float | None) - Optional - The stake of each bet.

### Request Example
```python
from sportsbet.evaluation import OddsComparisonBettor

bettor = OddsComparisonBettor(odds_types=['market_average'], alpha=0.03, init_cash=1000, stake=10)
```

### Response
#### Success Response (200)
- **OddsComparisonBettor instance** - An initialized OddsComparisonBettor object.

#### Response Example
```json
{
  "message": "OddsComparisonBettor initialized successfully"
}
```
```

--------------------------------

### Initialize OddsComparisonBettor - Python

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Initializes the OddsComparisonBettor with specified odds types, alpha adjustment, betting markets, initial cash, and stake. The default odds types are determined if not provided.

```python
def __init__(
    self: Self,
    odds_types: list[str] | None = None,
    alpha: float = 0.05,
    betting_markets: list[str] | None = None,
    init_cash: float | None = None,
    stake: float | None = None,
) -> None:
    super().__init__(betting_markets, init_cash, stake)
    self.odds_types = odds_types
    self.alpha = alpha
```

--------------------------------

### CLI: Show available odds types

Source: https://georgedouzas.github.io/sports-betting

Use this command to list the supported odds types for dataloaders via the CLI. A configuration file must be specified.

```bash
sportsbet dataloader odds-types -c config.py

```

--------------------------------

### SoccerDataLoader Initialization

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Initializes the SoccerDataLoader with an optional parameter grid to filter the data.

```APIDOC
## SoccerDataLoader(param_grid=None)

### Description
Dataloader for soccer data. It downloads historical and fixtures data for various leagues, years and divisions.

### Parameters
#### Path Parameters
- **param_grid** (ParamGrid | None) - Optional - 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.

### Method
__init__
```

--------------------------------

### Run Project Tests

Source: https://georgedouzas.github.io/sports-betting/development/contributing

Execute all project tests. This command ensures that the codebase functions as expected and that new changes haven't introduced regressions.

```bash
pdm tests
```

--------------------------------

### CLI: Extract fixtures data

Source: https://georgedouzas.github.io/sports-betting

Use this command to extract fixtures data and save it as CSV files. Specify the configuration file and the output directory.

```bash
sportsbet dataloader fixtures -c config.py -d /path/to/directory

```

--------------------------------

### Run All Project Checks

Source: https://georgedouzas.github.io/sports-betting/development/contributing

Execute all project checks, including quality, types, and dependency vulnerability scans. This provides a comprehensive overview of the project's health.

```bash
pdm checks all
```

--------------------------------

### Apply All Development Checks

Source: https://georgedouzas.github.io/sports-betting/development/contributing

Run all project checks as part of the development workflow. This ensures code quality and correctness before committing.

```bash
pdm checks
```

--------------------------------

### Create New Development Branch

Source: https://georgedouzas.github.io/sports-betting/development/contributing

Create a new branch for development work. It's recommended to use descriptive branch names.

```bash
git checkout -b new-branch-name
```

--------------------------------

### Initialize ClassifierBettor

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Initializes the ClassifierBettor with a Scikit-Learn classifier and optional betting parameters. Requires a classifier object that implements fit, score, and predict_proba.

```python
def __init__(
    self: Self,
    classifier: BaseEstimator,
    betting_markets: list[str] | None = None,
    init_cash: float | None = None,
    stake: float | None = None,
) -> None:
    super().__init__(betting_markets, init_cash, stake)
    self.classifier = classifier
```

--------------------------------

### CLI: Backtest bettor

Source: https://georgedouzas.github.io/sports-betting

This command performs backtesting of the configured bettor and saves the results as a CSV file. Provide the configuration file and the output directory.

```bash
sportsbet bettor backtest -c config.py -d /path/to/directory

```

--------------------------------

### BettorGridSearchCV Constructor

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Initializes BettorGridSearchCV for hyperparameter optimization.

```APIDOC
## BettorGridSearchCV(estimator, param_grid, *, scoring=None, n_jobs=None, refit=True, cv=TSCV, verbose=0, pre_dispatch='2*n_jobs', error_score=np.nan, return_train_score=False)

### Description
Exhaustive search over specified parameter values for a bettor. BettorGridSearchCV implements a `fit`, a `predict`, a `predict_proba`, a `bet` and a `score` method. The parameters of the bettor used to apply these methods are optimized by cross-validated grid-search over a parameter grid.

### Parameters
#### Estimator
- **estimator** (BaseBettor) - Required - The bettor estimator to tune.

#### Parameter Grid
- **param_grid** (dict | list) - Required - Dictionary with parameters names as keys and lists of parameter settings to try as values, or a list of such dictionaries.

#### Scoring
- **scoring** (str | Callable | list | tuple | dict[str, Callable] | None) - Optional - Strategy to evaluate the performance of the cross-validated model.

#### Parallel Jobs
- **n_jobs** (int | None) - Optional - Number of jobs to run in parallel. `None` means 1 unless in a `joblib.parallel_backend` context. `-1` means using all processors.

#### Refit
- **refit** (bool | str | Callable) - Optional - Refit an estimator using the best found parameters on the whole dataset.

#### Cross-Validation Strategy
- **cv** (TimeSeriesSplit) - Optional - Provides train/test indices to split time series data samples.

#### Verbosity
- **verbose** (int) - Optional - Controls the verbosity: the higher, the more messages.

#### Pre-dispatch
- **pre_dispatch** (int | str) - Optional - Controls the number of jobs that get dispatched during parallel execution.

#### Error Score
- **error_score** (str | float | int) - Optional - Value to assign to the score if an error occurs in estimator fitting.

#### Return Train Score
- **return_train_score** (bool) - Optional - If `False`, the `cv_results_` attribute will not include training scores.

### Attributes
- **cv_results_**: A dict with keys as column headers and values as columns, that can be imported into a pandas `DataFrame`.
```

--------------------------------

### CLI: Extract training data

Source: https://georgedouzas.github.io/sports-betting

This command extracts training data using the specified configuration file and saves it as CSV files in the given directory. Ensure the configuration file is correctly set up.

```bash
sportsbet dataloader training -c config.py -d /path/to/directory

```

--------------------------------

### Build Changelog

Source: https://georgedouzas.github.io/sports-betting/development/contributing

Generate the project's changelog. This command is useful for keeping track of changes between releases.

```bash
pdm changelog
```

--------------------------------

### Extract Training Data

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Prepares training data by selecting relevant input, output, and target columns, handling missing values, converting data types, and extracting odds information. This method is crucial for setting up the dataset before model training.

```python
target_keys = [col.split('__')[2:] for col in self._cols(data, 'target')]
odds_keys = [col.split('__')[2:] for col in self._cols(data, 'odds') if col.split('__')[1] == self.odds_type_]
output_keys = [
    key
    for key in (odds_keys if self.odds_type_ is not None else output_keys)
    if key in output_keys and key[-1:] in target_keys
]
target_output_keys = list({key for *_, key in output_keys})
self.input_cols_ = pd.Index(
    [col for col in self._cols(data, 'input') if col not in self.dropped_na_cols_],
    dtype=object,
)
self.odds_cols_ = pd.Index(
    [f'odds__{self.odds_type_}__{key1}__{key2}' for key1, key2 in output_keys if self.odds_type_ is not None],
    dtype=object,
)
self.output_cols_ = pd.Index(
    [f'output__{key1}__{key2}' for key1, key2 in output_keys if key2 in target_output_keys],
    dtype=object,
)
self.target_cols_ = pd.Index(
    [col for col in self._cols(data, 'target') if col.split('__')[-1] in target_output_keys],
    dtype=object,
)

# Remove missing target data
data = data.dropna(subset=self.target_cols_, how='any')

# Convert data types
data = self._convert_data_types(data)

# Extract outputs
Y_train = []
outputs_mapping = dict(self.OUTPUTS)
for col in self.output_cols_:
    func = outputs_mapping[col]
    Y_train.append(pd.Series(func(data[self.target_cols_]), name=col))
Y_train = pd.concat(Y_train, axis=1).reset_index(drop=True)

# Extract odds
O_train = data[self.odds_cols_].reset_index(drop=True) if self.odds_type_ is not None else None

self.train_data_ = data[self.input_cols_], Y_train, O_train
if hasattr(self, 'fixtures_data_'):
    delattr(self, 'fixtures_data_')

return self.train_data_
```

--------------------------------

### Import SoccerDataLoader

Source: https://georgedouzas.github.io/sports-betting/generated/gallery/plot_soccer_data.ipynb

Import the SoccerDataLoader class from the sportsbet.datasets module. This is the primary class used for loading soccer data.

```python
# Author: Georgios Douzas <gdouzas@icloud.com>
# Licence: MIT

from sportsbet.datasets import SoccerDataLoader
```

--------------------------------

### Check for Dependency Vulnerabilities

Source: https://georgedouzas.github.io/sports-betting/development/contributing

Scan project dependencies for known vulnerabilities. This is a crucial step for maintaining security.

```bash
pdm checks dependencies
```

--------------------------------

### Load Dummy Soccer Data

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide/bettor

Loads dummy training and fixtures data for soccer matches using DummySoccerDataLoader. This data is essential for fitting and testing the bettor.

```python
from sportsbet.datasets import DummySoccerDataLoader
dataloader = DummySoccerDataLoader()
X_train, Y_train, O_train = dataloader.extract_train_data(odds_type='interwetten')
X_fix, Y_fix, O_fix = dataloader.extract_fixtures_data()
```

--------------------------------

### BettorGridSearchCV Constructor

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Initializes the BettorGridSearchCV object with an estimator, parameter grid, and cross-validation strategy.

```APIDOC
## BettorGridSearchCV(estimator, param_grid, *, scoring=None, n_jobs=None, refit=True, cv=TSCV, verbose=0, pre_dispatch='2*n_jobs', error_score=np.nan, return_train_score=False)

### Description
Initializes the BettorGridSearchCV object with an estimator, parameter grid, and cross-validation strategy.

### Parameters
- **estimator** (BaseBettor) - The betting model estimator to tune.
- **param_grid** (dict | list) - Dictionary or list of dictionaries with parameters to explore.
- **scoring** (str | Callable | list | tuple | dict[str, Callable] | None) - Strategy to evaluate the performance of the cross-validated model on the test set.
- **n_jobs** (int | None) - Number of jobs to run in parallel. None means 1.
- **refit** (bool | str | Callable) - If True, refit an estimator using the best found parameters on the whole dataset. If an integer, it is the number of samples with the largest score to keep for refitting. If callable, it is used to select the best estimator. By default, it is True.
- **cv** (TimeSeriesSplit) - Determines the cross-validation splitting strategy. Defaults to TSCV.
- **verbose** (int) - Controls the verbosity: the higher, the more messages.
- **pre_dispatch** (int | str) - Controls how many jobs or how much of the input is   dispatched to the workers; see documentation for scikit-learn's GridSearchCV.
- **error_score** (str | float | int) - Value to assign to an estimator for an invalid response. Set to np.nan to use NaN, or an integer/float to set a specific value. If the estimator raises error in `fit` or `score` and this is not set to `np.nan`, then the error is ignored and the error score is assigned to the estimator. This does not cover `fit` or `score` exceptions that are not related to invalid input.
- **return_train_score** (bool) - If `False`, the scores of the training samples for each cv fold are not stored. Otherwise, they are. Defaults to False.

### Attributes
- **best_estimator_** | Estimator that was chosen by the search, i.e. estimator which gave highest score (or smallest loss if specified) on the left out data. Not available if `refit=False`.
- **best_score_** | Mean cross-validated score of the best_estimator For multi-metric evaluation, this is present only if `refit` is specified. This attribute is not available if `refit` is a function.
- **best_params_** | Parameter setting that gave the best results on the hold out data. For multi-metric evaluation, this is present only if `refit` is specified.
- **best_index_** | The index (of the `cv_results_` arrays) which corresponds to the best candidate parameter setting. For multi-metric evaluation, this is present only if `refit` is specified.
- **scorer_** | Scorer function used on the held out data to choose the best parameters for the model. For multi-metric evaluation, this attribute holds the validated `scoring` dict which maps the scorer key to the scorer callable.
- **n_splits_** | The number of cross-validation splits (folds/iterations).
- **refit_time_** | Seconds used for refitting the best model on the whole dataset. This is present only if `refit` is not False.
- **multimetric_** | Whether or not the scorers compute several metrics.
- **classes_** | The classes labels. This is present only if `refit` is specified and the underlying estimator is a classifier.
- **n_features_in_** | Number of features seen during `fit`. Only defined if `best_estimator_` is defined and that `best_estimator_` exposes `n_features_in_` when fit.
- **feature_names_in_** | Names of features seen during `fit`. Only defined if `best_estimator_` is defined and that `best_estimator_` exposes `feature_names_in_` when fit.

### Example
```python
>>> from sportsbet.evaluation import BettorGridSearchCV, OddsComparisonBettor, backtest
>>> from sportsbet.datasets import SoccerDataLoader
>>> from sklearn.model_selection import TimeSeriesSplit
>>> # Select only backtesting data for the Italian and Spanish leagues and years 2019 - 2022
>>> param_grid = {'league': ['Italy', 'Spain'], 'year': [2019, 2020, 2021, 2022]}
>>> dataloader = SoccerDataLoader(param_grid)
>>> # Select the market maximum odds
>>> X, Y, O = dataloader.extract_train_data(
... odds_type='market_maximum',
... )
>>> # Backtest the bettor
>>> bettor = BettorGridSearchCV(
... estimator=OddsComparisonBettor(),
... param_grid={'alpha': [0.02, 0.05, 0.1, 0.2, 0.3]},
... cv=TimeSeriesSplit(2),
... )
>>> backtest(bettor, X, Y, O, cv=TimeSeriesSplit(2)).reset_index()
  Training start ... Yield percentage per bet (under_2.5__full_time_goals)
...
```
```

--------------------------------

### Initialize ClassifierBettor

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide

Initialize a ClassifierBettor with a scikit-learn pipeline including imputation and a KNeighborsClassifier. This object is used for model evaluation and prediction.

```python
from sportsbet.evaluation import ClassifierBettor, backtest
from sklearn.neighbors import KNeighborsClassifier
from sklearn.impute import SimpleImputer
from sklearn.pipeline import make_pipeline
bettor = ClassifierBettor(classifier=make_pipeline(SimpleImputer(), KNeighborsClassifier()))
```

--------------------------------

### Verify Fixtures Target Matrix is None

Source: https://georgedouzas.github.io/sports-betting/overview/user_guide/dataloader

Confirms that the target matrix (Y_fix) for fixtures data is None, as it is not applicable.

```python
assert Y_fix is None
```

--------------------------------

### Format Only Docstrings

Source: https://georgedouzas.github.io/sports-betting/development/contributing

Run this command to format only the docstrings. This is helpful when you need to adjust documentation formatting without affecting the code.

```bash
pdm formatting docstrings
```

--------------------------------

### Import necessary libraries

Source: https://georgedouzas.github.io/sports-betting/generated/gallery/modelling/plot_classifier_bettor.ipynb

Imports required modules for data loading, preprocessing, modeling, and evaluation.

```python
# Author: Georgios Douzas <gdouzas@icloud.com>
# Licence: MIT

from sklearn.impute import SimpleImputer
from sklearn.model_selection import TimeSeriesSplit, cross_val_score
from sklearn.neighbors import KNeighborsClassifier
from sklearn.pipeline import make_pipeline

from sportsbet.datasets import SoccerDataLoader
from sportsbet.evaluation import ClassifierBettor, backtest
```

--------------------------------

### Initialize BaseBettor

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Initializes the base class for bettors. This class should not be used directly; use derived classes instead.

```python
def __init__(
    self: Self,
    betting_markets: list[str] | None = None,
    init_cash: float | None = None,
    stake: float | None = None,
) -> None:
    self.betting_markets = betting_markets
    self.init_cash = init_cash
    self.stake = stake
```

--------------------------------

### Display Backtesting Results

Source: https://georgedouzas.github.io/sports-betting/generated/gallery/modelling/plot_classifier_bettor.ipynb

Display the calculated backtesting statistics for the bettor.

```python
backtesting_results
```

--------------------------------

### Load and extract soccer training data

Source: https://georgedouzas.github.io/sports-betting/generated/gallery/modelling/plot_classifier_bettor.ipynb

Loads historical soccer data for specified leagues and years, dropping rows with too many missing values and selecting market maximum odds.

```python
dataloader = SoccerDataLoader(param_grid={'league': ['Spain'], 'year': [2020, 2021, 2022]})
X_train, Y_train, O_train = dataloader.extract_train_data(drop_na_thres=0.5, odds_type='market_maximum')
```

--------------------------------

### Load Bettor Object

Source: https://georgedouzas.github.io/sports-betting/api/evaluation

Loads a bettor object from a specified file path. Ensure the file exists and contains a valid pickled bettor object.

```python
def load_bettor(path: str) -> BaseBettor:
    """Load the bettor object.

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

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

--------------------------------

### Load Dataloader from Pickle File

Source: https://georgedouzas.github.io/sports-betting/api/datasets

Loads a BaseDataLoader object from a specified pickled file path. Requires the 'cloudpickle' library.

```python
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
```
Tokens:
Raw