### Install uv

Source: https://github.com/probberechts/soccerdata/blob/master/docs/contributing.md

Install the uv package manager on macOS and Linux using curl.

```console
curl -LsSf https://astral.sh/uv/install.sh | sh
```

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

### Set up development environment with pip

Source: https://github.com/probberechts/soccerdata/blob/master/docs/contributing.md

Create and activate a virtual environment using pip, then install the project and its dependencies.

```console
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m pip install -r requirements.txt
```

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

### Install uv with curl

Source: https://github.com/probberechts/soccerdata/blob/master/CONTRIBUTING.rst

Use curl to download and execute the uv installation script on macOS and Linux.

```bash
$ curl -LsSf https://astral.sh/uv/install.sh | sh
```

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

### Install project dependencies with pip

Source: https://github.com/probberechts/soccerdata/blob/master/CONTRIBUTING.rst

Install the project in editable mode and its requirements using pip.

```bash
$ python -m pip install -e .
$ python -m pip install -r requirements.txt
```

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

### Read Match Lineups with FBref

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/FBref.ipynb

Retrieves the starting lineups and substitutions for a given match ID. Use this to get player information for a specific game.

```python
lineups = fbref.read_lineup(match_id="db261cb0")
lineups.head()
```

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

### Install SoccerData using pip

Source: https://github.com/probberechts/soccerdata/blob/master/docs/intro.md

Install the soccerdata library using pip. This command ensures you have the latest version available.

```bash
python3 -m pip install soccerdata
```

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

### Instantiate FBref Scraper

Source: https://github.com/probberechts/soccerdata/blob/master/docs/intro.md

Create an instance of the FBref scraper class to begin fetching data from fbref.com. No additional setup is required for basic usage.

```python
import soccerdata as sd

# Create scraper class instance
fbref = sd.FBref()
```

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

### Initialize FBref Scraper and Fetch Data

Source: https://github.com/probberechts/soccerdata/blob/master/README.rst

Demonstrates how to create an instance of the FBref scraper for a specific league and season, and then fetch game schedules and team/player statistics. Ensure the soccerdata library is installed.

```python
import soccerdata as sd

# Create a scraper class instance for the 2020/21 Premier League
fbref = sd.FBref('ENG-Premier League', '2021')

# Fetch data
games = fbref.read_schedule()
team_season_stats = fbref.read_team_season_stats(stat_type="passing")
player_season_stats = fbref.read_player_season_stats(stat_type="standard")
```

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

### Enable Tor proxy with default settings

Source: https://github.com/probberechts/soccerdata/blob/master/docs/howto/proxy.md

Use this when Tor is running on the default localhost:9050. Ensure Tor is started before running this code.

```python
ws = sd.WhoScored(proxy='tor')
```

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

### get(url, filepath=None, max_age=None, no_cache=False, var=None)

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/matchhistory.md

Loads data from a specified URL, with options for caching and file path management. It can download data, use cached versions, or return specific JavaScript variables.

```APIDOC
## Method: get(url, filepath=None, max_age=None, no_cache=False, var=None)

### Description
Load data from url. By default, the source of url is downloaded and saved to filepath. If filepath exists, the url is not visited and the cached data is returned.

### Parameters
* **url** (str) – URL to download.
* **filepath** (Path, optional) – Path to save downloaded file. If None, downloaded data is not cached.
* **max_age** (int for age in days, or timedelta object) – The max. age of locally cached file before re-download.
* **no_cache** (bool) – If True, will not use cached data. Overrides the class property.
* **var** (str or list of str, optional) – Return a JavaScript variable instead of the page source.

### Raises
**TypeError** – If max_age is not an integer or timedelta object.

### Returns
File-like object of downloaded data.

### Return Type
io.BufferedIOBase
```

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

### Get Data from URL

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/understat.md

Load data from a given URL, with options for caching and proxy usage.

```APIDOC
## get(url, filepath=None, max_age=None, no_cache=False, var=None)

### Description
Load data from url. By default, the source of url is downloaded and saved to filepath. If filepath exists, the url is not visited and the cached data is returned.

### Parameters
* **url** (*str*): URL to download.
* **filepath** (*Path*, *optional*): Path to save downloaded file. If None, downloaded data is not cached.
* **max_age** (*int for age in days* *, or* *timedelta object*): The max. age of locally cached file before re-download.
* **no_cache** (*bool*): If True, will not use cached data. Overrides the class property.
* **var** (*str* *or* *list* *of* *str*, *optional*): Return a JavaScript variable instead of the page source.

### Raises
* **TypeError**: If max_age is not an integer or timedelta object.

### Returns
File-like object of downloaded data.

### Return Type
io.BufferedIOBase
```

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

### Get Data from URL

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/espn.md

Load data from a given URL. This method handles downloading and caching of data.

```APIDOC
## get(url, filepath=None, max_age=None, no_cache=False, var=None)

Load data from url.

By default, the source of url is downloaded and saved to filepath.
If filepath exists, the url is not visited and the cached data is
returned.

### Parameters:
* **url** (*str*) – URL to download.
* **filepath** (*Path* *,* *optional*) – Path to save downloaded file. If None, downloaded data is not cached.
* **max_age** (*int for age in days* *, or* *timedelta object*) – The max. age of locally cached file before re-download.
* **no_cache** (*bool*) – If True, will not use cached data. Overrides the class property.
* **var** (*str* *or* *list* *of* *str* *,* *optional*) – Return a JavaScript variable instead of the page source.
### Raises:
**TypeError** – If max_age is not an integer or timedelta object.
### Returns:
File-like object of downloaded data.
### Return type:
io.BufferedIOBase
```

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

### Update Pre-commit Hooks

Source: https://github.com/probberechts/soccerdata/blob/master/CONTRIBUTING.rst

Install or update pre-commit as a Git hook to automatically run linting and code formatting checks before each commit.

```console
$ make pre-commit-update
```

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

### Available Leagues

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/understat.md

Get a list of league IDs that are available for the Understat data source.

```APIDOC
## available_leagues()

### Description
Return a list of league IDs available for this source.

### Return Type
list[str]
```

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

### get

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/clubelo.md

Loads data from a given URL. By default, it downloads and saves the data to a specified filepath, caching it locally. If the filepath exists, cached data is returned without visiting the URL.

```APIDOC
## get(url, filepath=None, max_age=None, no_cache=False, var=None)

### Description
Load data from url.

By default, the source of url is downloaded and saved to filepath.
If filepath exists, the url is not visited and the cached data is
returned.

### Parameters
* **url** (*str*) – URL to download.
* **filepath** (*Path* *,* *optional*) – Path to save downloaded file. If None, downloaded data is not cached.
* **max_age** (*int for age in days* *, or* *timedelta object*) – The max. age of locally cached file before re-download.
* **no_cache** (*bool*) – If True, will not use cached data. Overrides the class property.
* **var** (*str* *or* *list* *of* *str* *,* *optional*) – Return a JavaScript variable instead of the page source.

### Raises
**TypeError** – If max_age is not an integer or timedelta object.

### Returns
File-like object of downloaded data.

### Return type
io.BufferedIOBase
```

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

### Read FBref Match Schedule

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/FBref.ipynb

Reads the match schedule from FBref. Use this to get an overview of games played in a season. The output includes game details like date, time, and participating teams.

```python
epl_schedule = fbref.read_schedule()
epl_schedule.head()
```

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

### Pull Latest Test Data with DVC

Source: https://github.com/probberechts/soccerdata/blob/master/CONTRIBUTING.rst

Use this command to fetch the most recent test data from the DVC remote storage. Ensure DVC is installed and configured.

```console
$ uv run dvc pull
```

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

### Read Player Season Stats - FBref

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/FBref.ipynb

Reads standard player season statistics from FBref. Use this to get a DataFrame of player performance data for a given season.

```python
player_season_stats = fbref.read_player_season_stats(stat_type="standard")
player_season_stats.head()
```

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

### Read Player Match Stats

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/Understat.ipynb

Reads player match statistics from the Understat data source. Use this to get detailed per-game performance data for players.

```python
player_match_stats = understat.read_player_match_stats()
player_match_stats.head()
```

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

### Load Atomic Actions for a Specific Match

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/WhoScored.ipynb

Reads match event data for a given match ID and formats it as atomic SPADL actions. Use this to get granular event data for analysis.

```python
atomic_actions = ws.read_events(match_id=1485184, output_fmt="atomic-spadl")
atomic_actions.head()
```

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

### Run the full test suite

Source: https://github.com/probberechts/soccerdata/blob/master/CONTRIBUTING.rst

Execute the entire test suite for the project using the make command.

```bash
$ make test
```

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

### Create and activate virtual environment with uv

Source: https://github.com/probberechts/soccerdata/blob/master/docs/contributing.md

Create a virtual environment using uv with Python 3.10 and activate it.

```console
uv venv --python 3.10
source .venv/bin/activate
```

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

### Initialize FBref Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/FBref.ipynb

Instantiate the FBref data source by specifying the leagues and seasons of interest. This prepares the object for data retrieval.

```python
fbref = sd.FBref(leagues="ENG-Premier League", seasons=2021)
print(fbref.__doc__)
```

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

### Available Leagues

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/espn.md

Get a list of all league IDs that are available for the ESPN data source.

```APIDOC
## available_leagues()

Return a list of league IDs available for this source.

### Return type:
list[str]
```

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

### Create and activate uv virtual environment

Source: https://github.com/probberechts/soccerdata/blob/master/CONTRIBUTING.rst

Create a virtual environment using uv with a specified Python version and activate it.

```bash
$ uv venv --python 3.10
$ source .venv/bin/activate
```

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

### Initialize MatchHistory Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/MatchHistory.ipynb

Initializes the MatchHistory data source for a specific league and season. The data will be downloaded and cached if not already present.

```python
mh = sd.MatchHistory(leagues="ENG-Premier League", seasons=2021)
print(mh.__doc__)
```

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

### Initialize Understat Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/Understat.ipynb

Instantiate the Understat data source for a specific league and season. This prepares the object for data retrieval.

```python
understat = sd.Understat(leagues="ENG-Premier League", seasons="2015/2016")
print(understat.__doc__)
```

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

### Create and activate pip virtual environment

Source: https://github.com/probberechts/soccerdata/blob/master/CONTRIBUTING.rst

Create a virtual environment using Python's venv module and activate it.

```bash
python3 -m venv .venv
$ source .venv/bin/activate
```

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

### Read SoFIFA Players by Team

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/SoFIFA.ipynb

Fetches player data for a specific team from SoFIFA. Use this to get a DataFrame of players belonging to a particular team, such as 'Arsenal'.

```python
sofifa.read_players(team="Arsenal")
```

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

### Instantiate FBref Scraper with Filters

Source: https://github.com/probberechts/soccerdata/blob/master/docs/intro.md

Create an instance of the FBref scraper, filtering data retrieval to specific leagues and seasons. This is useful for focusing on particular data subsets.

```python
# Create scraper class instance filtering on specific leagues and seasons
fbref = sd.FBref(leagues=['ENG-Premier League'], seasons=['1718', '1819'])
# Retrieve data for the specified leagues and seasons
season_stats = fbref.read_team_season_stats(stat_type='shooting')
```

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

### Initialize ClubElo Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/ClubElo.ipynb

Instantiate the ClubElo data source. You can configure caching, storage, and proxy settings during initialization.

```APIDOC
## Initialize ClubElo

### Description
Instantiates the ClubElo data source, allowing access to ELO ratings from clubelo.com. Supports configuration for caching, storage, and proxy usage.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **proxy** (str or dict or list or callable, optional): Proxy configuration for network requests. Can be 'tor', a dictionary, a list of dictionaries, or a callable function.
- **no_cache** (bool, optional): If True, disables caching of downloaded data.
- **no_store** (bool, optional): If True, disables storing downloaded data.
- **data_dir** (Path, optional): Specifies the directory for caching data.
```

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

### Read FIFA Team Ratings

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/SoFIFA.ipynb

Fetches EA Sports FIFA team ratings. Use this to get a DataFrame of team performance metrics across different leagues and FIFA editions.

```python
team_ratings = sofifa.read_team_ratings()
team_ratings.head()
```

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

### Initialize SoFIFA data source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/SoFIFA.ipynb

Initializes the SoFIFA data source for a specific league and version. This downloads and caches data from sofifa.com. The `__doc__` attribute provides detailed information about the class and its parameters.

```python
sofifa = sd.SoFIFA(leagues="ENG-Premier League", versions="latest")
print(sofifa.__doc__)
```

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

### FBref Class Initialization

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/fbref.md

Initializes the FBref class to access data. You can specify leagues, seasons, and caching options.

```APIDOC
## soccerdata.FBref

### Description
Provides pd.DataFrames from data at http://fbref.com. Data will be downloaded as necessary and cached locally.

### Parameters
* **leagues** (string or iterable, optional) – IDs of leagues to include. For efficiently reading data from the Top-5 European leagues, use “Big 5 European Leagues Combined”.
* **seasons** (string, int or list, optional) – Seasons to include. Supports multiple formats. Examples: ‘16-17’; 2016; ‘2016-17’; [14, 15, 16]
* **proxy** ('tor' or or dict or list(dict) or callable, optional) – Use a proxy to hide your IP address.
* **no_cache** (bool) – If True, will not use cached data.
* **no_store** (bool) – If True, will not store downloaded data.
* **data_dir** (Path) – Path to directory where data will be cached.
* **path_to_browser** (Path, optional) – Path to the Chrome executable.
* **headless** (bool, default: True) – If True, will run Chrome in headless mode. Setting this to False might help to avoid getting blocked. Only supported for Selenium <4.13.
```

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

### Import FBref Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/index.md

Import the FBref data source. This is used for historical results, lineups, and detailed aggregated statistics.

```python
from soccerdata import FBref
```

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

### Initialize ESPN Datasource

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/ESPN.ipynb

Instantiate the ESPN datasource object for a specific league and season. This may issue a UserWarning if the season format is ambiguous.

```python
espn = sd.ESPN(leagues="ENG-Premier League", seasons=2021)
print(espn.__doc__)
```

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

### MatchHistory Class Initialization

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/matchhistory.md

Initializes the MatchHistory object to fetch game data. Users can specify leagues, seasons, and caching behavior.

```APIDOC
## Class: MatchHistory

### Description
Provides pd.DataFrames from CSV files available at http://www.football-data.co.uk/data.php. Data will be downloaded as necessary and cached locally.

### Parameters
* **leagues** (string or iterable) – IDs of leagues to include.
* **seasons** (string, int or list) – Seasons to include. Supports multiple formats (e.g., ‘16-17’; 2016; ‘2016-17’; [14, 15, 16]).
* **proxy** ('tor' or str or list(dict) or callable, optional) – Use a proxy to hide your IP address. Options include 'tor', a proxy server address, a list of proxies, or a callable function that returns a proxy.
* **no_cache** (bool) – If True, will not use cached data.
* **no_store** (bool) – If True, will not store downloaded data.
* **data_dir** (Path, optional) – Path to directory where data will be cached.
```

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

### Run Pre-commit Test Hooks

Source: https://github.com/probberechts/soccerdata/blob/master/CONTRIBUTING.rst

Execute the pre-commit test hooks to ensure code conforms to PEP 8 style guidelines and other project-specific formatting rules before committing.

```console
$ make pre-commit-test
```

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

### Read Raw Match Events

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/WhoScored.ipynb

Retrieves raw match event data for a given match ID. Use 'output_fmt="raw"' to get the original JSON structure. Requires the 'json' library for pretty printing.

```python
events = ws.read_events(match_id=1485184, output_fmt="raw")

import json  # noqa

print(json.dumps(events[1485184][0], indent=2))
```

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

### List Available Leagues with FBref

Source: https://github.com/probberechts/soccerdata/blob/master/docs/howto/custom-leagues.md

Use the `available_leagues()` class method from the FBref module to see a list of leagues that SoccerData can scrape.

```python
import soccerdata as sd
sd.FBref.available_leagues()
>>> ['ENG-Premier League', 'ESP-La Liga', 'FRA-Ligue 1', 'GER-Bundesliga', 'ITA-Serie A']
```

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

### Read Player Season Stats

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/Understat.ipynb

Fetches player season statistics from the Understat data source. Use this to get a DataFrame containing detailed player performance data per season. The `.head()` method displays the first 5 rows.

```python
player_season_stats = understat.read_player_season_stats()
player_season_stats.head()
```

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

### Understat Class Initialization

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/understat.md

Initialize the Understat class to access data. You can specify leagues, seasons, and proxy settings.

```APIDOC
## Understat Class

### Description
Provides pd.DataFrames from data at https://understat.com. Data will be downloaded as necessary and cached locally.

### Parameters
* **proxy** (*'tor'* *or* *dict* *or* *list* *or* *callable*, *optional*): Use a proxy to hide your IP address. Options include 'tor', a proxy server address, a list of proxies, or a callable function.
* **no_cache** (*bool*): If True, will not use cached data.
* **no_store** (*bool*): If True, will not store downloaded data.
* **data_dir** (*Path*): Path to directory where data will be cached.
* **leagues** (*str* *|* *list* *[**str* *]* *|* *None*): Specify leagues to retrieve data for.
* **seasons** (*str* *|* *int* *|* *Iterable* *[**str* *|* *int* *]* *|* *None*): Specify seasons to retrieve data for.
```

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

### Import MatchHistory Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/index.md

Import the MatchHistory data source. This is used for historical results, betting odds and match statistics.

```python
from soccerdata import MatchHistory
```

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

### Initialize ClubElo Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/ClubElo.ipynb

Import the soccerdata library and initialize the ClubElo data source object. This object will be used to access ELO rating data.

```python
import soccerdata as sd
```

```python
elo = sd.ClubElo()
```

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

### Initialize WhoScored datasource

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/WhoScored.ipynb

Initializes the WhoScored datasource for a specific league and season. A UserWarning may appear if the season format is ambiguous.

```python
ws = sd.WhoScored(leagues="ENG-Premier League", seasons=2021)
print(ws.__doc__)
```

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

### Initialize Sofascore Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/Sofascore.ipynb

Initializes the Sofascore data source for specified leagues and seasons. The data is downloaded and cached locally. Use this to set up data retrieval for specific competitions.

```python
sofascore = sd.Sofascore(leagues="ESP-La Liga", seasons="2022/2023")
print(sofascore.__doc__)
```

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

### Import Soccerdata Library

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/Sofascore.ipynb

Imports the soccerdata library, typically aliased as 'sd' for brevity.

```python
import soccerdata as sd
```

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

### Instantiate WhoScored Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/WhoScored.ipynb

This snippet shows how to create an instance of the WhoScored data source, specifying the desired leagues and seasons. It also includes a print statement for the data source's documentation.

```APIDOC
## Instantiate WhoScored Data Source

### Description
Provides pd.DataFrames from data available at http://whoscored.com.

Data will be downloaded as necessary and cached locally in
`~/soccerdata/data/WhoScored`.

### Parameters
#### Optional Parameters
- **leagues** (string or iterable, optional): IDs of Leagues to include.
- **seasons** (string, int or list, optional): Seasons to include. Supports multiple formats.
    Examples: '16-17'; 2016; '2016-17'; [14, 15, 16]
- **proxy** ('tor' or dict or list(dict) or callable, optional): Use a proxy to hide your IP address. Valid options are:
    - "tor": Uses the Tor network. Tor should be running in
      the background on port 9050.
    - dict: A dictionary with the proxy to use. The dict should be
      a mapping of supported protocols to proxy addresses. For example::

          {
              'http': 'http://10.10.1.10:3128',
              'https': 'http://10.10.1.10:1080',
          }

    - list(dict): A list of proxies to choose from. A different proxy will
      be selected from this list after failed requests, allowing rotating
      proxies.
    - callable: A function that returns a valid proxy. This function will
      be called after failed requests, allowing rotating proxies.
- **no_cache** (bool): If True, will not use cached data.
- **no_store** (bool): If True, will not store downloaded data.
- **data_dir** (Path): Path to directory where data will be cached.
- **path_to_browser** (Path, optional): Path to the Chrome executable.
- **headless** (bool, default: True): If True, will run Chrome in headless mode. Setting this to False might
    help to avoid getting blocked. Only supported for Selenium <4.13.

### Usage Example
```python
import soccerdata as sd

ws = sd.WhoScored(leagues="ENG-Premier League", seasons=2021)
print(ws.__doc__)
```
```

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

### Visualize Win Percentage per Team with FacetGrid

Source: https://github.com/probberechts/soccerdata/blob/master/docs/examples/MatchHistory - Home advantage.ipynb

Creates a series of point plots, one for each team, showing their win percentage at home and away. This helps identify teams that deviate from the general home advantage trend. Requires seaborn and pandas.

```python
g = sns.FacetGrid(results.reset_index(), col="team", col_wrap=5)
g.map(sns.pointplot, "is_home", "win_pct", order=["Away", "Home"])
g.set_axis_labels("", "win %");
```

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

### Import Understat Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/index.md

Import the Understat data source. This is used for advanced statistics such as xG, xGBuildup and xGChain.

```python
from soccerdata import Understat
```

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

### Load and Display Match Data using Loader

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/WhoScored.ipynb

Initializes a loader to scrape all games and then uses it to load and display games, teams, players, and events for a specific competition and season. This is useful for accessing comprehensive datasets.

```python
# Scrape all games and return a socceration.data.opta.OptaLoader
loader = ws.read_events(output_fmt="loader")

# Now use this loader to load the data
print("Games:")
df_games = loader.games(competition_id="ENG-Premier League", season_id="2021")
display(df_games.head())

print("Teams:")
df_teams = loader.teams(game_id=1485184)
display(df_teams.head())

print("Players:")
df_players = loader.players(game_id=1485184)
display(df_players.head())

print("Events:")
df_events = loader.events(game_id=1485184)
display(df_events.head())

# You can use the socceraction package to convert the events
# to SPADL and to compute xT or VAEP action values
```

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

### BaseSeleniumReader.get()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Fetches data using BaseSeleniumReader, likely for specific leagues or seasons.

```APIDOC
## BaseSeleniumReader.get()

### Description
Fetches data from the data source.

### Method
(Not specified in source, likely a method call)

### Endpoint
(Not applicable, SDK method)

### Parameters
(No parameters specified in source)

### Request Example
(No request example provided in source)

### Response
#### Success Response
(Type not specified, likely data records)

#### Response Example
(No response example provided in source)
```

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

### _common.get_proxy

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/utils.md

Retrieves a public proxy server configuration.

```APIDOC
## _common.get_proxy()

### Description
Return a public proxy.

### Return type
dict[str, str]
```

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

### Configure Plotting and Import Libraries

Source: https://github.com/probberechts/soccerdata/blob/master/docs/examples/MatchHistory - Home advantage.ipynb

Sets up the plotting environment for inline display and imports pandas and seaborn for data manipulation and visualization. This is standard practice for data analysis in Python.

```python
%matplotlib inline
%config InlineBackend.figure_format = 'retina'

import pandas as pd
import seaborn as sns

sns.set_context("notebook")
sns.set_style("whitegrid")
```

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

### Configure Plotting Environment

Source: https://github.com/probberechts/soccerdata/blob/master/docs/examples/ClubElo - Evolution of current top teams.ipynb

Set up the plotting environment for inline display and high-resolution figures. Imports pandas, matplotlib, and seaborn for data manipulation and visualization.

```python
%matplotlib inline
%config InlineBackend.figure_format = 'retina'

import matplotlib.pyplot as plt
import pandas as pd
import seaborn as sns

sns.set_context("notebook")
sns.set_style("whitegrid")
```

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

### SoFIFA Class Initialization

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/sofifa.md

Initializes the SoFIFA class with optional parameters to filter data by leagues and versions, and control caching and proxy usage.

```APIDOC
## soccerdata.SoFIFA

Provides pd.DataFrames from data at http://sofifa.com.

Data will be downloaded as necessary and cached locally in
`~/soccerdata/data/SoFIFA`.

### Parameters:
* **leagues** (*string* *or* *iterable* *,* *optional*) – IDs of leagues to include.
* **versions** (*string* *,* *int* *or* *list* *of* *int* *,* *optional*) – FIFA releases to include. Should be specified by their ID used in the URL
  (e.g., 230034). Alternatively, the string “all” can be used to include all
  versions and “latest” to include the latest version only. Defaults to
  “latest”.
* **proxy** ( *'tor'* *or* *or dict* *or* *list* *(**dict* *) or* *callable* *,* *optional*) – 

  Use a proxy to hide your IP address. Valid options are:
  : - ”tor”: Uses the Tor network. Tor should be running in
      the background on port 9050.
    - str: The address of the proxy server to use.
    - list(str): A list of proxies to choose from. A different proxy will
      be selected from this list after failed requests, allowing rotating
      proxies.
    - callable: A function that returns a valid proxy. This function will
      be called after failed requests, allowing rotating proxies.
* **no_cache** (*bool*) – If True, will not use cached data.
* **no_store** (*bool*) – If True, will not store downloaded data.
* **data_dir** (*Path*) – Path to directory where data will be cached.
* **path_to_browser** (*Path* *,* *optional*) – Path to the Chrome executable.
* **headless** (*bool* *,* *default: True*) – If True, will run Chrome in headless mode. Setting this to False might
  help to avoid getting blocked. Only supported for Selenium <4.13.
```

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

### Import WhoScored Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/index.md

Import the WhoScored data source. This is used for historical results, match preview data and detailed Opta event stream data.

```python
from soccerdata import WhoScored
```

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

### Load and Sample Serie A Match History

Source: https://github.com/probberechts/soccerdata/blob/master/docs/examples/MatchHistory - Home advantage.ipynb

Loads historical match data for the Italian Serie A from 2018 to 2023 and samples 5 random games. This is useful for initial data exploration.

```python
seriea_hist = sd.MatchHistory("ITA-Serie A", range(2018, 2023))
games = seriea_hist.read_games()
games.sample(5)
```

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

### Configure Custom League in league_dict.json

Source: https://github.com/probberechts/soccerdata/blob/master/docs/howto/custom-leagues.md

Add a new league to your SoccerData configuration by defining its mapping to data source identifiers in `SOCCERDATA_DIR/config/league_dict.json`. The `season_start` and `season_end` fields are optional.

```json
{
  "NED-Eredivisie": {
    "ClubElo": "NED_1",
    "MatchHistory": "N1",
    "SoFIFA": "[Netherlands] Eredivisie",
    "FBref": "Eredivisie",
    "ESPN": "ned.1",
    "FiveThirtyEight": "eredivisie",
    "WhoScored": "Netherlands - Eredivisie",
    "Sofascore": "Eredivisie",
    "season_start": "Aug",
    "season_end": "May"
  }
}
```

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

### Verify Custom League Loading Logs

Source: https://github.com/probberechts/soccerdata/blob/master/docs/howto/custom-leagues.md

Check log messages upon importing soccerdata to confirm if custom league and team name replacement files are being loaded correctly. Ensure the file paths in the logs match your configuration.

```python
>>> import soccerdata as sd
[11/25/22 11:49:12] INFO     Custom team name replacements loaded from <path>/teamname_replacements.json.                                                                                                _config.py:83
                       INFO     Custom league dict loaded from <path>/league_dict.json.                                                                                                                    _config.py:153
```

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

### BaseSeleniumReader.available_leagues()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Retrieves a list of available leagues from the data source using BaseSeleniumReader.

```APIDOC
## BaseSeleniumReader.available_leagues()

### Description
Retrieves a list of available leagues.

### Method
(Not specified in source, likely a method call)

### Endpoint
(Not applicable, SDK method)

### Parameters
(No parameters specified in source)

### Request Example
(No request example provided in source)

### Response
#### Success Response
(Type not specified, likely a list of leagues)

#### Response Example
(No response example provided in source)
```

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

### Initialize ClubElo and Read Current Ratings

Source: https://github.com/probberechts/soccerdata/blob/master/docs/examples/ClubElo - Evolution of current top teams.ipynb

Initialize the ClubElo class and read the current Elo ratings for all clubs. The result is a pandas DataFrame indexed by team name.

```python
elo = sd.ClubElo()
current_elo = elo.read_by_date()
current_elo.head()
```

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

### Verify Custom League Addition

Source: https://github.com/probberechts/soccerdata/blob/master/docs/howto/custom-leagues.md

After updating `league_dict.json`, restart your Python session and use `sd.FBref.available_leagues()` again to confirm that your custom league has been added to the list of available leagues.

```python
>>> import soccerdata as sd
>>> sd.FBref.available_leagues()
[..., 'NED-Eredivisie', ...]
```

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

### FBref.available_leagues()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Retrieves a list of leagues available in the FBref dataset.

```APIDOC
## FBref.available_leagues()

### Description
Retrieves a list of leagues available in the FBref dataset.

### Method
Not specified (assumed to be a method call within a Python library)

### Response
* **Leagues** (list) - A list of available league names.
```

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

### ESPN.read_lineup()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Reads the lineup information for a match from ESPN.

```APIDOC
## ESPN.read_lineup()

### Description
Reads the lineup information for a match from ESPN.

### Method
Not specified (assumed to be a method call within a Python library)

### Parameters
* **match_id** (str) - Required - The unique identifier for the match.

### Response
* **Lineup** (DataFrame) - Lineup information for the match.
```

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

### FBref.read_lineup()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Reads the lineup information for a match from FBref.

```APIDOC
## FBref.read_lineup()

### Description
Reads the lineup information for a match from FBref.

### Method
Not specified (assumed to be a method call within a Python library)

### Parameters
* **match_id** (str) - Required - The unique identifier for the match.

### Response
* **Lineup** (DataFrame) - Lineup information for the match.
```

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

### ClubElo Class Initialization

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/clubelo.md

Initializes the ClubElo class. You can specify a proxy for requests, disable caching or storage, and set a custom data directory.

```APIDOC
## soccerdata.ClubElo

### Description
Provides pd.DataFrames from CSV API at [http://api.clubelo.com](http://api.clubelo.com).
Data will be downloaded as necessary and cached locally in `~/soccerdata/data/ClubElo`.

### Parameters
* **proxy** (*'tor'* *or* *or dict* *or* *list* *(**dict* *) or* *callable* *,* *optional*) – 

  Use a proxy to hide your IP address. Valid options are:
  : - ”tor”: Uses the Tor network. Tor should be running in
      the background on port 9050.
    - str: The address of the proxy server to use.
    - list(str): A list of proxies to choose from. A different proxy will
      be selected from this list after failed requests, allowing rotating
      proxies.
    - callable: A function that returns a valid proxy. This function will
      be called after failed requests, allowing rotating proxies.
* **no_cache** (*bool*) – If True, will not use cached data.
* **no_store** (*bool*) – If True, will not store downloaded data.
* **data_dir** (*Path*) – Path to directory where data will be cached.
```

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

### Import SoFIFA Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/index.md

Import the SoFIFA data source. This is used for detailed scores on all player’s abilities from EA Sports FC.

```python
from soccerdata import SoFIFA
```

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

### Import ClubElo Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/index.md

Import the ClubElo data source. This is used for Team’s relative strengths as Elo ratings.

```python
from soccerdata import ClubElo
```

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

### Import ESPN Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/index.md

Import the ESPN data source. This is used for historical results, statistics and lineups.

```python
from soccerdata import ESPN
```

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

### Configure Understat Logging and Caching

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/Understat.ipynb

Set environment variables to control Understat's logging level and caching behavior. This is useful for managing output and performance.

```python
%env SOCCERDATA_LOGLEVEL=ERROR
%env SOCCERDATA_NOCACHE=False
%env SOCCERDATA_NOSTORE=False
```

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

### Configure soccerdata Environment Variables

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/FBref.ipynb

Set environment variables to control logging level, caching, and data storage for the soccerdata library. This is useful for managing output and performance.

```python
import pandas as pd

pd.set_option("display.max_columns", None)
```

```shell
%env SOCCERDATA_LOGLEVEL=ERROR
%env SOCCERDATA_NOCACHE=True
%env SOCCERDATA_NOSTORE=True
```

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

### Run pytest with custom SOCCERDATA_DIR

Source: https://github.com/probberechts/soccerdata/blob/master/docs/contributing.md

Run pytest for a specific test file while setting the SOCCERDATA_DIR environment variable to save downloaded data to the test data directory.

```console
SOCCERDATA_DIR=tests/appdata uv run pytest tests/test_MyNewScraper.py
```

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

### Read Match Events with FBref

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/FBref.ipynb

Retrieves in-game events for a given match ID. Use this to analyze specific occurrences within a match.

```python
events = fbref.read_events(match_id="db261cb0")
events.head()
```

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

### Player Information Data

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/WhoScored.ipynb

This snippet shows the structure of player information within a match, including player ID, name, starter status, and minutes played.

```python
Result:
   game_id  team_id  player_id      player_name  is_starter  minutes_played  \
0  1485184      184     105720        Nick Pope        True             102   
1  1485184      184      80067   Matthew Lowton        True             102   
2  1485184      184      94935          Ben Mee        True             102   
3  1485184      184     131464  James Tarkowski        True             102   
4  1485184      184      24148     Erik Pieters        True             102   

   jersey_number starting_position  
0              1                GK  
1              2                DR  
2              6                DC  
3              5                DC  
4             23                DL  
```

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

### SoFIFA.read_versions()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Reads available game versions from SoFIFA.

```APIDOC
## SoFIFA.read_versions()

### Description
Reads available game versions from SoFIFA.

### Method
Not specified (assumed to be a method call within a Python library)

### Response
* **Versions** (DataFrame) - A DataFrame containing game version information.
```

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

### ESPN Class Initialization

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/espn.md

Initialize the ESPN class to access ESPN soccer data. You can specify leagues, seasons, proxy settings, and cache behavior.

```APIDOC
## soccerdata.ESPN

Provides pd.DataFrames from JSON api available at [http://site.api.espn.com](http://site.api.espn.com).

Data will be downloaded as necessary and cached locally in
`~/soccerdata/data/ESPN`.

### Parameters:
* **leagues** (*string* *or* *iterable* *,* *optional*) – IDs of leagues to include.
* **seasons** (*string* *,* *int* *or* *list* *,* *optional*) – Seasons to include. Supports multiple formats.
  Examples: ‘16-17’; 2016; ‘2016-17’; [14, 15, 16]
* **proxy** ( *'tor'* *or* *or dict* *or* *list* *(**dict* *) or* *callable* *,* *optional*) – 

  Use a proxy to hide your IP address. Valid options are:
  : - ”tor”: Uses the Tor network. Tor should be running in
      the background on port 9050.
    - str: The address of the proxy server to use.
    - list(str): A list of proxies to choose from. A different proxy will
      be selected from this list after failed requests, allowing rotating
      proxies.
    - callable: A function that returns a valid proxy. This function will
      be called after failed requests, allowing rotating proxies.
* **no_cache** (*bool*) – If True, will not use cached data.
* **no_store** (*bool*) – If True, will not store downloaded data.
* **data_dir** (*Path*) – Path to directory where data will be cached.
```

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

### Configure SoccerData Environment Variables

Source: https://github.com/probberechts/soccerdata/blob/master/docs/intro.md

Set these environment variables in your bash shell to control SoccerData's behavior, such as cache directory, cache usage, storage, and log level.

```bash
# bash
export SOCCERDATA_DIR = "~/soccerdata"
export SOCCERDATA_NOCACHE = "False"
export SOCCERDATA_NOSTORE = "False"
export SOCCERDATA_LOGLEVEL = "INFO"
```

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

### Import Sofascore Data Source

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/index.md

Import the Sofascore data source. This is used for results, schedules, lineups, and detailed statistics.

```python
from soccerdata import Sofascore
```

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

### Visualize Win Percentage by Home/Away Status

Source: https://github.com/probberechts/soccerdata/blob/master/docs/examples/MatchHistory - Home advantage.ipynb

Generates a point plot to visualize the win percentage for each team, comparing their performance at home versus away. Requires seaborn and pandas.

```python
g = sns.FacetGrid(results.reset_index(), hue="team", palette="Set2", height=6, aspect=0.5)
g.map(sns.pointplot, "is_home", "win_pct", order=["Away", "Home"])
g.set_axis_labels("", "win %");
```

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

### FBref.read_schedule()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Reads the match schedule from FBref for a given league and season.

```APIDOC
## FBref.read_schedule()

### Description
Reads the match schedule from FBref for a given league and season.

### Method
Not specified (assumed to be a method call within a Python library)

### Parameters
* **league** (str) - Required - The league.
* **season** (str) - Required - The season.

### Response
* **Schedule** (DataFrame) - The match schedule.
```

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

### MatchHistory.available_leagues()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Retrieves a list of leagues available in the MatchHistory dataset.

```APIDOC
## MatchHistory.available_leagues()

### Description
Retrieves a list of leagues available in the MatchHistory dataset.

### Method
Not specified (assumed to be a method call within a Python library)

### Response
* **Leagues** (list) - A list of available league names.
```

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

### Read Team Match Stats with Understat

Source: https://github.com/probberechts/soccerdata/blob/master/docs/datasources/Understat.ipynb

Reads team match statistics from the Understat datasource. Use this to access detailed match data for analysis.

```python
team_match_stats = understat.read_team_match_stats()
team_match_stats.head()
```

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

### SoFIFA.available_leagues()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Retrieves a list of leagues available in the SoFIFA dataset.

```APIDOC
## SoFIFA.available_leagues()

### Description
Retrieves a list of leagues available in the SoFIFA dataset.

### Method
Not specified (assumed to be a method call within a Python library)

### Response
* **Leagues** (list) - A list of available league names.
```

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

### FBref.read_leagues()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Reads a list of leagues from FBref.

```APIDOC
## FBref.read_leagues()

### Description
Reads a list of leagues from FBref.

### Method
Not specified (assumed to be a method call within a Python library)

### Response
* **Leagues** (DataFrame) - A DataFrame containing league information.
```

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

### WhoScored Class Initialization

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/whoscored.md

Initializes the WhoScored API client. You can specify leagues, seasons, and other options for data retrieval and caching.

```APIDOC
## soccerdata.WhoScored

Provides pd.DataFrames from data available at http://whoscored.com.

Data will be downloaded as necessary and cached locally in
`~/soccerdata/data/WhoScored`.

### Parameters:
* **leagues** (*string* *or* *iterable* *,* *optional*) – IDs of Leagues to include.
* **seasons** (*string* *,* *int* *or* *list* *,* *optional*) – Seasons to include. Supports multiple formats.
  Examples: ‘16-17’; 2016; ‘2016-17’; [14, 15, 16]
* **proxy** ( *'tor'* *or* *or dict* *or* *list* *(**dict* *) or* *callable* *,* *optional*) – 

  Use a proxy to hide your IP address. Valid options are:
  : - ”tor”: Uses the Tor network. Tor should be running in
      the background on port 9050.
    - str: The address of the proxy server to use.
    - list(str): A list of proxies to choose from. A different proxy will
      be selected from this list after failed requests, allowing rotating
      proxies.
    - callable: A function that returns a valid proxy. This function will
      be called after failed requests, allowing rotating proxies.
* **no_cache** (*bool*) – If True, will not use cached data.
* **no_store** (*bool*) – If True, will not store downloaded data.
* **data_dir** (*Path*) – Path to directory where data will be cached.
* **path_to_browser** (*Path* *,* *optional*) – Path to the Chrome executable.
* **headless** (*bool* *,* *default: True*) – If True, will run Chrome in headless mode. Setting this to False might
  help to avoid getting blocked. Only supported for Selenium <4.13.
```

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

### Calculate and Plot Smoothed Elo Development

Source: https://github.com/probberechts/soccerdata/blob/master/docs/examples/ClubElo - Evolution of current top teams.ipynb

Fetch the Elo history for the top 5 teams, calculate a rolling mean for smoothing, and plot the development over time. Adjust 'num_teams' and 'smoothing' parameters as needed.

```python
num_teams = 5
smoothing = 100
elo_top_development = pd.concat(
    [
        elo.read_team_history(team)("elo").rolling(smoothing).mean()
        for team in current_elo.reset_index()["team"][:num_teams]
    ],
    axis=1,
)
elo_top_development.columns = current_elo.reset_index()["team"][:num_teams]
elo_top_development.fillna(method="ffill")

fig = plt.figure(figsize=(16, 10))
ax1 = fig.add_subplot(111, ylabel="ELO rolling avg.", xlabel="Date")
elo_top_development.plot(ax=ax1)
ax1.legend(loc="upper left", frameon=False, bbox_to_anchor=(0, 1.05), ncol=num_teams)
sns.despine();
```

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

### FBref.read_events()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Reads match events from FBref.

```APIDOC
## FBref.read_events()

### Description
Reads match events from FBref.

### Method
Not specified (assumed to be a method call within a Python library)

### Parameters
* **match_id** (str) - Required - The unique identifier for the match.

### Response
* **Events** (DataFrame) - Match events data.
```

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

### ESPN.available_leagues()

Source: https://github.com/probberechts/soccerdata/blob/master/docs/reference/index.md

Retrieves a list of leagues available in the ESPN dataset.

```APIDOC
## ESPN.available_leagues()

### Description
Retrieves a list of leagues available in the ESPN dataset.

### Method
Not specified (assumed to be a method call within a Python library)

### Response
* **Leagues** (list) - A list of available league names.
```