### Install development version from source

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/install.rst

Methods for installing the development version directly from the GitHub repository or by cloning the source code locally.

```console
pip install git+https://github.com/ML-KULeuven/socceraction.git
```

```console
git clone git://github.com/ML-KULeuven/socceraction.git
```

```console
curl -OL https://github.com/ML-KULeuven/socceraction/archive/master.zip
```

```console
cd socceraction
python -m pip install -e .
```

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

### Verify socceraction installation

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/install.rst

Verify that the library is correctly installed by importing it within a Python shell and checking the version.

```python
import socceraction
print(socceraction.__version__)
```

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

### Install and Run Pre-commit Hooks for Code Formatting

Source: https://github.com/ml-kuleuven/socceraction/blob/master/CONTRIBUTING.rst

This command installs the pre-commit framework as a Git hook. It ensures that code formatting and linting checks are automatically performed before each commit, helping to maintain code consistency across the project. This is crucial for adhering to the project's coding standards.

```console
$ nox --session=pre-commit -- install
```

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

### Install socceraction with StatsBomb support

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/intro.rst

Installs the socceraction library with the necessary dependencies for StatsBomb data. This is the first step to using the library's features.

```console
pip install socceraction[statsbomb]
```

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

### Install SoccerAction with StatsBomb dependencies

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/statsbomb.rst

Installs the socceraction library with the necessary dependencies for StatsBomb data integration. This is a prerequisite for using the StatsBombLoader.

```console
pip install "socceraction[statsbomb]"
```

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

### Load Game Data and Prepare Training/Testing Sets

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/3-estimate-scoring-and-conceding-probabilities.ipynb

Loads game data from a HDF5 file using pandas and prints the number of games. It then sets up training and testing datasets, using the same data for both in this example due to the small dataset size.

```python
games = pd.read_hdf(spadl_h5, "games")
print("nb of games:", len(games))

# note: only for the purpose of this example and due to the small dataset,
# we use the same data for training and evaluation
traingames = games
testgames = games
```

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

### Install Socceraction Package

Source: https://github.com/ml-kuleuven/socceraction/blob/master/README.md

Installs the socceraction package using pip. This package is compatible with Python 3.9 and above.

```sh
pip install socceraction
```

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

### Install socceraction via pip

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/install.rst

The recommended method for installing the latest official version of the socceraction library using the Python package manager.

```console
python -m pip install socceraction
```

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

### Initialize OptaLoader for StatsPerform MA1 and MA3 JSON Feeds

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/opta.rst

Initializes the OptaLoader for StatsPerform MA1 and MA3 JSON feeds. This setup is for data provided by StatsPerform, with a specific directory structure and file naming convention. The 'statsperform' parser is utilized.

```python
from socceraction.data.opta import OptaLoader

api = OptaLoader(root="data/statsperform", parser="statsperform")
```

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

### Action Start and End Location Features

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/valuing_actions/vaep.rst

Details about the starting and ending coordinates of an action on the pitch.

```APIDOC
## Action Start and End Location Features

### Description
This section describes the features related to the starting and ending coordinates of a soccer action on the pitch.

### Features

- **start_y_ai** (float) - The y pitch coordinate of the action's start location.
- **end_x_ai** (float) - The x pitch coordinate of the action's end location.
- **end_y_ai** (float) - The y pitch coordinate of the action's end location.
```

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

### GET /competitions

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/statsbomb.rst

Retrieves a list of all available competitions.

```APIDOC
## GET /competitions

### Description
Fetches a DataFrame containing all available competitions from the configured data source.

### Method
GET

### Endpoint
api.competitions()

### Response
#### Success Response (200)
- **df_competitions** (DataFrame) - A table containing season_id, competition_id, competition_name, country_name, competition_gender, and season_name.
```

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

### GET /atomic/config

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/api/spadl_atomic.rst

Retrieves configuration constants and metadata for the atomic SPADL schema.

```APIDOC
## GET /atomic/config

### Description
Fetches field dimensions, action types, and body part mappings used in the atomic SPADL schema.

### Method
GET

### Endpoint
/atomic/config

### Response
#### Success Response (200)
- **field_length** (float) - Length of the pitch.
- **field_width** (float) - Width of the pitch.
- **actiontypes** (dict) - Mapping of action IDs to names.
- **bodyparts** (dict) - Mapping of body part IDs to names.

#### Response Example
{
  "field_length": 105.0,
  "field_width": 68.0,
  "actiontypes": {"0": "pass", "1": "dribble"},
  "bodyparts": {"0": "foot", "1": "head"}
}
```

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

### Scrape WhoScored Data and Get OptaLoader Object using soccerdata

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/opta.rst

Demonstrates how to use the soccerdata library to scrape WhoScored.com data for a specified league and season, and then directly obtain an OptaLoader object configured for this data. This simplifies the process of loading WhoScored data.

```python
import soccerdata as sd

# Setup a scraper for the 2021/2022 Premier League season
ws = sd.WhoScored(leagues="ENG-Premier League", seasons=2021)
# Scrape all games and return a OptaLoader object
api = ws.read_events(output_fmt='loader')
```

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

### Initialize Environment and Load Data

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/EXTRA-run-xT.ipynb

Sets up the environment by importing necessary libraries and loading game data from an HDF5 file.

```python
import os
import tqdm
import pandas as pd
import numpy as np
%load_ext autoreload
%autoreload 2
import socceraction.spadl as spadl
import socceraction.vaep.features as fs
import socceraction.xthreat as xthreat

datafolder = "../data-fifa"
spadl_h5 = os.path.join(datafolder, "spadl-statsbomb.h5")
games = pd.read_hdf(spadl_h5, "games")
```

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

### Initialize Environment and Load Data Paths

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/EXTRA-build-expected-goals-model.ipynb

Sets up the necessary Python environment, imports required libraries for SPADL and VAEP, and defines the file paths for HDF5 data storage.

```python
import os
import warnings
import tqdm
import numpy as np
import pandas as pd
warnings.simplefilter(action='ignore', category=pd.errors.PerformanceWarning)
%load_ext autoreload
%autoreload 2
import socceraction.spadl as spadl
import socceraction.vaep.features as fs
import socceraction.vaep.labels as lab
datafolder = "../data-fifa"
spadl_h5 = os.path.join(datafolder, "spadl-statsbomb.h5")
features_h5 = os.path.join(datafolder, "features.h5")
labels_h5 = os.path.join(datafolder, "labels.h5")
predictions_h5 = os.path.join(datafolder, "predictions.h5")
```

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

### Initialize Environment and Load Libraries

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/ATOMIC-2-compute-features-and-labels.ipynb

Sets up the Python environment by importing necessary data science libraries and configuring the autoreload extension for development.

```python
import os
import warnings
import tqdm
import pandas as pd
warnings.simplefilter(action='ignore', category=pd.errors.PerformanceWarning)
%load_ext autoreload
%autoreload 2
import socceraction.atomic.spadl as atomicspadl
import socceraction.atomic.vaep.features as fs
import socceraction.atomic.vaep.labels as lab
```

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

### Initialize WyscoutLoader with API Credentials (Python)

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/wyscout.rst

Demonstrates how to initialize the WyscoutLoader to fetch data from the Wyscout API. Authentication can be handled by setting environment variables for username and password or by passing credentials directly in a dictionary to the constructor. The 'getter' argument must be set to 'remote'.

```python
from socceraction.data.wyscout import WyscoutLoader

# set authentication credentials as environment variables
import os
os.environ["WY_USERNAME"] = "your_client_id"
os.environ["WY_PASSWORD"] = "your_secret"
api = WyscoutLoader(getter="remote")

# or provide authentication credentials as a dictionary
api = WyscoutLoader(getter="remote", creds={"user": "", "passwd": ""})
```

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

### Configure File and Folder Paths

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/4-compute-vaep-values-and-top-players.ipynb

Sets up the file and folder names for data storage, specifically for SPADL and prediction data in HDF5 format.

```python
# Configure file and folder names
datafolder = "../data-fifa"
spadl_h5 = os.path.join(datafolder, "spadl-statsbomb.h5")
predictions_h5 = os.path.join(datafolder, "predictions.h5")
```

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

### Initialize Environment and Load Data

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/ATOMIC-4-compute-vaep-values-and-top-players.ipynb

Sets up the necessary libraries and file paths to access atomic SPADL data and prediction files.

```python
import os
import warnings
import tqdm
import pandas as pd
import socceraction.atomic.spadl as atomicspadl
import socceraction.atomic.vaep.formula as vaepformula

warnings.simplefilter(action='ignore', category=pd.errors.PerformanceWarning)

datafolder = "../data-fifa"
spadl_h5 = os.path.join(datafolder, "atomic-spadl-statsbomb.h5")
predictions_h5 = os.path.join(datafolder, "atomic-predictions-one-action.h5")
```

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

### Load public Wyscout dataset with PublicWyscoutLoader

Source: https://context7.com/ml-kuleuven/socceraction/llms.txt

Shows how to initialize the PublicWyscoutLoader to access the free Wyscout dataset. It covers retrieving available competitions, listing games for a specific competition, and loading event data for analysis.

```python
from socceraction.data.wyscout import PublicWyscoutLoader

# Initialize loader - downloads data to specified folder on first run
loader = PublicWyscoutLoader(root="./wyscout_data", download=False)

# Get available competitions
competitions = loader.competitions()

# Get games from Serie A 2017/18
games = loader.games(competition_id=524, season_id=181248)

# Load teams, players, and events for a specific game
game_id = games.iloc[0].game_id
teams = loader.teams(game_id)
players = loader.players(game_id)
events = loader.events(game_id)
```

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

### Initialize WyscoutLoader from Local Directory (Python)

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/wyscout.rst

Shows how to initialize the WyscoutLoader to load data from a local directory. The 'getter' argument should be set to 'local' and the 'root' argument should specify the path to the data directory. This method assumes a default directory structure for competitions, seasons, matches, and events.

```python
from socceraction.data.wyscout import WyscoutLoader

ap = WyscoutLoader(getter="local", root="data/wyscout")
```

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

### GET /teams

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/statsbomb.rst

Retrieves teams associated with a specific game.

```APIDOC
## GET /teams

### Description
Fetches the teams participating in a specific game.

### Method
GET

### Endpoint
api.teams(game_id)

### Parameters
#### Query Parameters
- **game_id** (int) - Required - The unique identifier for the match.

### Response
#### Success Response (200)
- **df_teams** (DataFrame) - A table containing team_id and team_name.
```

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

### GET /games

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/statsbomb.rst

Retrieves a list of games for a specific competition and season.

```APIDOC
## GET /games

### Description
Fetches a list of games for a given competition and season.

### Method
GET

### Endpoint
api.games(competition_id, season_id)

### Parameters
#### Query Parameters
- **competition_id** (int) - Required - The ID of the competition.
- **season_id** (int) - Required - The ID of the season.

### Response
#### Success Response (200)
- **df_games** (DataFrame) - A table containing game details such as game_id, home_team_id, away_team_id, and scores.
```

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

### Initialize OptaLoader

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/opta.rst

Configures the OptaLoader with a root directory and specific parser settings to handle local data files.

```APIDOC
## POST /OptaLoader/initialize

### Description
Initializes the OptaLoader instance by specifying the root directory where data files are stored and the parser type or mapping to be used for processing.

### Method
POST

### Parameters
#### Request Body
- **root** (string) - Required - The path to the root directory containing the data files.
- **parser** (string/dict) - Required - The parser type (e.g., 'xml', 'json', 'statsperform', 'whoscored') or a dictionary mapping feed types to specific parser classes.
- **feeds** (dict) - Optional - A mapping of feed identifiers to file path templates using placeholders like {competition_id}, {season_id}, and {game_id}.

### Request Example
{
  "root": "data/opta",
  "parser": "xml",
  "feeds": {
    "f7": "f7-{competition_id}-{season_id}.xml",
    "f24": "f24-{competition_id}-{season_id}-{game_id}.xml"
  }
}

### Response
#### Success Response (200)
- **instance** (object) - Returns the configured OptaLoader instance.
```

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

### Converting StatsBomb Data to SPADL

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/spadl/spadl.rst

Example of loading StatsBomb event data and converting it to the SPADL format.

```python
from socceraction.data.statsbomb import StatsBombLoader
import socceraction.spadl as spadl

# Initialize the StatsBomb loader
SBL = StatsBombLoader()

# Load event data for a specific game (e.g., game_id=8657)
df_events = SBL.events(game_id=8657)

# Convert events to SPADL format, specifying the home team ID
df_actions = spadl.statsbomb.convert_to_actions(df_events, home_team_id=777)

# Add names for action types, results, teams, and players
df_actions = (
    spadl
    .add_names(df_actions)  # add actiontype and result names
    .merge(SBL.teams(game_id=8657))  # add team names
    .merge(SBL.players(game_id=8657))  # add player names
)

# The resulting df_actions dataframe is now in SPADL format with added names.
```

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

### Initialize OptaLoader with Generic Feed Configuration

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/opta.rst

Initializes the OptaLoader with a custom root directory and a dictionary defining the file hierarchy for different feeds. This allows for flexible data loading based on custom file naming conventions and structures. It requires specifying parsers for each feed type.

```python
from socceraction.data.opta import OptaLoader, parsers

api = OptaLoader(
  root="data/opta",
  feeds = {
      "f7": "f7-{competition_id}-{season_id}-{game_id}.xml",
      "f24": "f24-{competition_id}-{season_id}-{game_id}.xml",
  },
  parser={
      "f7": parsers.F7XMLParser,
      "f24": parsers.F24XMLParser
  }
)
```

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

### Initialize StatsBombLoader

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/ATOMIC-1-load-and-convert-statsbomb-data.ipynb

Sets up the StatsBombLoader to fetch data. It can be configured to use either remote public data or a local folder containing StatsBomb data.

```python
# Use this if you only want to use the free public statsbomb data
free_open_data_remote = "https://raw.githubusercontent.com/statsbomb/open-data/master/data/"
SBL = StatsBombLoader(root=free_open_data_remote, getter="remote")

# # Uncomment the code below if you have a local folder on your computer with statsbomb data
#datafolder = "../data-epl" # Example of local folder with statsbomb data
#SBL = statsbomb.StatsBombLoader(root=datafolder, getter="local")
```

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

### Initialize Environment and Load Data

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/2-compute-features-and-labels.ipynb

Configures the workspace by importing necessary libraries and defining file paths for SPADL data, features, and labels. It also demonstrates how to load game metadata from an HDF5 store.

```python
import os
import warnings
import tqdm
import pandas as pd
import socceraction.spadl as spadl
import socceraction.vaep.features as fs
import socceraction.vaep.labels as lab

datafolder = "../data-fifa"
spadl_h5 = os.path.join(datafolder, "spadl-statsbomb.h5")
features_h5 = os.path.join(datafolder, "features.h5")
labels_h5 = os.path.join(datafolder, "labels.h5")

games = pd.read_hdf(spadl_h5, "games")
print("nb of games:", len(games))
```

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

### Visualize Soccer Actions using Matplotlib

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/1-load-and-convert-statsbomb-data.ipynb

This Python code snippet visualizes a sequence of soccer actions on a pitch using the matplotsoccer library. It selects a specific set of actions preceding a goal, formats time and labels for clarity, and then plots the actions with details like player, team, and action type. An extra dependency is matplotsoccer, which can be installed via pip.

```python
import matplotsoccer
import pandas as pd

# Assuming 'actions' and 'game' DataFrames are already loaded and processed as in the previous snippet

# Select the 5 actions preceding the 2-0
shot = 2201
a = actions[shot-4:shot+1].copy()

# Print the game date and timestamp of the goal
g = game.iloc[0]
minute = int((a.period_id.values[0]-1) * 45 + a.time_seconds.values[0] // 60)
game_info = f"{g.game_date} {g.home_team_name} {g.home_score}-{g.away_score} {g.away_team_name} {minute + 1}'"
print(game_info)

# Plot the actions
def nice_time(row):
    minute = int((row.period_id-1)*45 +row.time_seconds // 60)
    second = int(row.time_seconds % 60)
    return f"{minute}m{second}s"

a["nice_time"] = a.apply(nice_time, axis=1)
labels = a[["nice_time", "type_name", "player_name", "team_name"]]

ax = matplotsoccer.actions(
    location=a[["start_x", "start_y", "end_x", "end_y"]],
    action_type=a.type_name,
    team= a.team_name,
    result= a.result_name == "success",
    label=labels,
    labeltitle=["time", "actiontype", "player", "team"],
    zoom=False,
    figsize=6
)
```

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

### Initialize OptaLoader for Opta F7 and F24 XML Feeds

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/opta.rst

Initializes the OptaLoader specifically for Opta F7 and F24 XML feeds. It assumes a predefined directory structure where XML files are organized by competition and season. The 'xml' parser is used for both feed types.

```python
from socceraction.data.opta import OptaLoader

api = OptaLoader(root="data/opta", parser="xml")
```

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

### Initialize OptaLoader for Opta F1, F9, and F24 JSON Feeds

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/opta.rst

Initializes the OptaLoader for Opta F1, F9, and F24 JSON feeds. This configuration expects JSON files organized in a specific structure within the root directory. The 'json' parser is used for these feed types.

```python
from socceraction.data.opta import OptaLoader

api = OptaLoader(root="data/opta", parser="json")
```

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

### Initialize WyscoutLoader with Custom Local Directory Structure (Python)

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/wyscout.rst

Illustrates how to configure the WyscoutLoader to read data from a local directory with a custom file hierarchy. The 'feeds' argument accepts a dictionary mapping data types (competitions, seasons, games, events) to their respective file paths, using placeholders like {competition_id}, {season_id}, and {game_id}.

```python
from socceraction.data.wyscout import WyscoutLoader

ap = WyscoutLoader(getter="local", root="data/wyscout", feeds={
    "competitions": "competitions.json",
    "seasons": "seasons_{competition_id}.json",
    "games": "matches_{season_id}.json",
    "events": "matches/events_{game_id}.json",
  })
```

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

### Initialize PublicWyscoutLoader for Public Dataset (Python)

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/wyscout.rst

Demonstrates how to use the PublicWyscoutLoader to load a publicly available Wyscout event stream dataset. This loader will download and extract the dataset to the specified 'root' directory. It is suitable for accessing the 2017/18 season data and major tournaments.

```python
from socceraction.data.wyscout import PublicWyscoutLoader

api = PublicWyscoutLoader(root="data/wyscout")
```

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

### Initialize StatsBombLoader and Fetch Competitions

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/1-load-and-convert-statsbomb-data.ipynb

This snippet initializes the StatsBombLoader to access public data and retrieves a list of all available competitions.

```python
from socceraction.data.statsbomb import StatsBombLoader
SBL = StatsBombLoader(getter="remote", creds={"user": None, "passwd": None})
competitions = SBL.competitions()
print(set(competitions.competition_name))
```

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

### Configure Data Paths and Load Games

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/ATOMIC-3-estimate-scoring-and-conceding-probabilities.ipynb

Sets up the file paths for SPADL, features, and labels HDF5 files, and loads the games metadata into a pandas DataFrame.

```python
import os
import pandas as pd

datafolder = "../data-fifa"
spadl_h5 = os.path.join(datafolder, "atomic-spadl-statsbomb.h5")
features_h5 = os.path.join(datafolder, "atomic-features.h5")
labels_h5 = os.path.join(datafolder, "atomic-labels.h5")

games = pd.read_hdf(spadl_h5, "games")
traingames = games
testgames = games
```

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

### Load StatsBomb event data with StatsBombLoader

Source: https://context7.com/ml-kuleuven/socceraction/llms.txt

Demonstrates how to initialize the StatsBombLoader to access either remote open data or local files. It shows how to retrieve competitions, filter by season, fetch game lists, and extract detailed event streams including optional 360 freeze-frame data.

```python
from socceraction.data.statsbomb import StatsBombLoader

# Initialize loader for remote StatsBomb open data
loader = StatsBombLoader(getter="remote", creds={"user": None, "passwd": None})

# Get available competitions and seasons
competitions = loader.competitions()

# Select FIFA World Cup 2018
world_cup = competitions[(competitions.competition_name == "FIFA World Cup") & (competitions.season_name == "2018")]
competition_id = world_cup.iloc[0].competition_id
season_id = world_cup.iloc[0].season_id

# Get all games in the competition
games = loader.games(competition_id, season_id)

# Get teams and players for a specific game
game_id = games.iloc[0].game_id
teams = loader.teams(game_id)
players = loader.players(game_id)

# Load event stream data for a game
events = loader.events(game_id)

# Load events with 360 freeze-frame data (when available)
events_360 = loader.events(game_id, load_360=True)
```

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

### Initializing and Fitting Expected Threat (xT) Model

Source: https://context7.com/ml-kuleuven/socceraction/llms.txt

Initializes an Expected Threat model with specified grid dimensions and fits it on historical soccer actions to learn threat values associated with pitch locations.

```python
from socceraction.xthreat import ExpectedThreat, load_model
import socceraction.spadl as spadl

# Initialize xT model with grid dimensions
xt = ExpectedThreat(l=16, w=12, eps=1e-5)  # 16x12 grid

# Fit model on historical actions
# Requires a large dataset of SPADL actions
all_games_actions = pd.concat(all_actions, ignore_index=True)
xt.fit(all_games_actions)

# Access learned matrices
print(f"xT grid shape: {xt.xT.shape}")  # (12, 16)
print(f"Scoring probability matrix: {xt.scoring_prob_matrix.shape}")
print(f"Shot probability matrix: {xt.shot_prob_matrix.shape}")
print(f"Move probability matrix: {xt.move_prob_matrix.shape}")
print(f"Transition matrix: {xt.transition_matrix.shape}")  # (192, 192)
```

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

### Load and Convert Event Data to SPADL

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/spadl/spadl.rst

Demonstrates how to initialize a data loader, retrieve event data for a specific game, and convert those events into the standardized SPADL format. This process requires a valid game ID and the home team ID for coordinate normalization.

```python
from socceraction.data.statsbomb import StatsBombLoader
import socceraction.spadl as spadl

SBL = StatsBombLoader()
df_events = SBL.events(game_id=8657)
df_actions = spadl.statsbomb.convert_to_actions(df_events, home_team_id=777)
```

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

### PublicWyscoutLoader - Load Free Wyscout Dataset

Source: https://context7.com/ml-kuleuven/socceraction/llms.txt

This section details the usage of PublicWyscoutLoader to access the free Wyscout dataset. It explains how to initialize the loader, retrieve competition and game information, and load team, player, and event data.

```APIDOC
## PublicWyscoutLoader - Load Free Wyscout Dataset

### Description
The PublicWyscoutLoader provides access to the publicly available Wyscout dataset containing event data from five major European leagues (2017/18), the 2018 World Cup, and Euro 2016. The data is automatically downloaded and cached locally.

### Method
N/A (Class Initialization and Methods)

### Endpoint
N/A (Local Data Access after download)

### Parameters
#### Initialization Parameters
- **root** (string) - Required - The directory where Wyscout data will be stored.
- **download** (bool) - Optional - Set to `True` to automatically download the dataset if it's not found (default is `False`).

### Methods
- **competitions()**: Returns a DataFrame of available competitions.
- **games(competition_id, season_id)**: Returns a DataFrame of games for a given competition and season.
- **teams(game_id)**: Returns a DataFrame of teams participating in a game.
- **players(game_id)**: Returns a DataFrame of players in a game.
- **events(game_id)**: Returns a DataFrame of event stream data for a game.

### Request Example
```python
from socceraction.data.wyscout import PublicWyscoutLoader

# Initialize loader - downloads data to specified folder on first run
loader = PublicWyscoutLoader(root="./wyscout_data", download=False)

# Get available competitions
competitions = loader.competitions()
print(competitions[["competition_id", "competition_name", "season_name"]])

# Get games from Serie A 2017/18
games = loader.games(competition_id=524, season_id=181248)

# Load teams, players, and events for a specific game
game_id = games.iloc[0].game_id
events = loader.events(game_id)
print(events[["type_name", "subtype_name", "player_id", "team_id"]])
```

### Response Example
```
# Output from competitions():
#    competition_id  competition_name  season_name
# 0             524          Serie A    2017/2018
# 1             364   Premier League    2017/2018
# 2             795          La Liga    2017/2018
# 3             412         Ligue 1    2017/2018
# 4             426      Bundesliga    2017/2018
# 5             102       Euro 2016         2016
# 6              28   FIFA World Cup         2018

# Output from events():
#   type_name subtype_name  player_id  team_id
# 0  Pass          None      12345    98765
# 1  Shot          Miss      54321    67890
```
```

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

### Train and Predict with xT Model

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/EXTRA-run-xT.ipynb

Initializes an Expected Threat model, fits it to the action data, and calculates xT values for successful ball-moving actions.

```python
xTModel = xthreat.ExpectedThreat(l=16, w=12)
xTModel.fit(A)
mov_actions = xthreat.get_successful_move_actions(A)
mov_actions["xT_value"] = xTModel.rate(mov_actions)
```

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

### Train and Apply Expected Threat Model

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/valuing_actions/xT.rst

This snippet demonstrates the full pipeline for the xT model: loading match events, converting them to SPADL format, training the model on a grid, and calculating xT values for successful ball-moving actions.

```python
import pandas as pd
from socceraction.data.statsbomb import StatsBombLoader
import socceraction.spadl as spadl
import socceraction.xthreat as xthreat

# 1. Load a set of actions to train the model on
SBL = StatsBombLoader()
df_games = SBL.games(competition_id=43, season_id=3)
dataset = [
    {
        **game,
        'actions': spadl.statsbomb.convert_to_actions(
            events=SBL.events(game['game_id']),
            home_team_id=game['home_team_id']
        )
    }
    for game in df_games.to_dict(orient='records')
]

# 2. Convert direction of play + add names
df_actions_ltr = pd.concat([
  spadl.play_left_to_right(game['actions'], game['home_team_id'])
  for game in dataset
])
df_actions_ltr = spadl.add_names(df_actions_ltr)

# 3. Train xT model with 16 x 12 grid
xTModel = xthreat.ExpectedThreat(l=16, w=12)
xTModel.fit(df_actions_ltr)

# 4. Rate ball-progressing actions
df_mov_actions = xthreat.get_successful_move_actions(df_actions_ltr)
df_mov_actions["xT_value"] = xTModel.rate(df_mov_actions)
```

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

### Initialize StatsBombLoader for StatsBomb API (Credentials Dictionary)

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/statsbomb.rst

Initializes the StatsBombLoader to fetch data from the official StatsBomb API by providing authentication credentials directly in a dictionary. This method is an alternative to using environment variables.

```python
from socceraction.data.statsbomb import StatsBombLoader

api = StatsBombLoader(getter="remote", creds={"user": "", "passwd": ""})
```

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

### Initialize StatsBombLoader for Local Data Directory

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/statsbomb.rst

Initializes the StatsBombLoader to load data from a local directory. The 'root' argument specifies the path to the directory containing the organized StatsBomb data files.

```python
from socceraction.data.statsbomb import StatsBombLoader

api = StatsBombLoader(getter="local", root="data/statsbomb")
```

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

### Run Pre-commit Checks with Nox

Source: https://github.com/ml-kuleuven/socceraction/blob/master/CONTRIBUTING.rst

This command executes the pre-commit session using Nox. It runs all configured pre-commit hooks to check and format the code, ensuring it meets the project's quality standards before submission. This is a manual check that can be run at any time.

```console
$ nox --session=pre-commit
```

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

### Initialize StatsBombLoader for StatsBomb API (Environment Variables)

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/statsbomb.rst

Initializes the StatsBombLoader to fetch data from the official StatsBomb API using environment variables for authentication. Ensure SB_USERNAME and SB_PASSWORD are set in your environment.

```python
from socceraction.data.statsbomb import StatsBombLoader

# set authentication credentials as environment variables
import os
os.environ["SB_USERNAME"] = "your_username"
os.environ["SB_PASSWORD"] = "your_password"
api = StatsBombLoader(getter="remote")
```

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

### Load Opta/Stats Perform Data

Source: https://context7.com/ml-kuleuven/socceraction/llms.txt

Enables loading of Opta and Stats Perform data in various feed formats (F1, F7, F9, F24, MA1, MA3, WhoScored). Supports different parsers and feed configurations. Requires specifying the root directory for data files.

```python
from socceraction.data.opta import OptaLoader

# Initialize loader with file patterns for different feeds
loader = OptaLoader(
    root="/path/to/opta/data",
    parser="whoscored",  # Options: "whoscored", "f1", "f7", "f9", "f24", "ma1", "ma3"
    feeds={
        "whoscored": "whoscored/matches/{game_id}.json"
    }
)

# For Stats Perform MA3 feed
loader = OptaLoader(
    root="/path/to/statsperform/data",
    parser="ma3",
    feeds={
        "ma3": "MA3_EPL_{game_id}.json"
    }
)

# Load events for a specific game
events = loader.events(game_id=12345)
teams = loader.teams(game_id=12345)
players = loader.players(game_id=12345)
```

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

### Initialize OptaLoader for WhoScored.com JSON Data

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/opta.rst

Initializes the OptaLoader to parse JSON data scraped from WhoScored.com. This configuration requires a specific directory structure for the scraped JSON files. The 'whoscored' parser is used.

```python
from socceraction.data.opta import OptaLoader

api = OptaLoader(root="data/whoscored", parser="whoscored")
```

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

### VAEP Framework: Load, Train, and Rate Actions with Socceraction

Source: https://context7.com/ml-kuleuven/socceraction/llms.txt

This Python code implements the VAEP framework to rate player actions. It loads data using StatsBombLoader, converts it to SPADL format, initializes and trains VAEP models (e.g., XGBoost) on computed features and labels, evaluates performance using AUROC scores, and finally rates actions for a specific game, combining them with the original action data.

```python
import pandas as pd
from socceraction.vaep import VAEP
from socceraction.data.statsbomb import StatsBombLoader
import socceraction.spadl as spadl
from socceraction.spadl import statsbomb as sb_spadl

# Load and convert data for multiple games
loader = StatsBombLoader(getter="remote")
competitions = loader.competitions()
world_cup = competitions[
    (competitions.competition_name == "FIFA World Cup") & 
    (competitions.season_name == "2018")
]
games = loader.games(world_cup.iloc[0].competition_id, world_cup.iloc[0].season_id)

# Convert all games to SPADL
all_actions = []
for game in games.itertuples():
    events = loader.events(game.game_id)
    actions = sb_spadl.convert_to_actions(events, game.home_team_id)
    actions = spadl.add_names(actions)
    all_actions.append(actions)

# Initialize VAEP model
vaep = VAEP(nb_prev_actions=3)  # Use 3 previous actions as context

# Compute features and labels for training
features_list = []
labels_list = []
for game, actions in zip(games.itertuples(), all_actions):
    game_series = pd.Series({
        "game_id": game.game_id,
        "home_team_id": game.home_team_id
    })
    X = vaep.compute_features(game_series, actions)
    y = vaep.compute_labels(game_series, actions)
    features_list.append(X)
    labels_list.append(y)

X_all = pd.concat(features_list, ignore_index=True)
y_all = pd.concat(labels_list, ignore_index=True)

# Train VAEP models
vaep.fit(
    X_all,
    y_all,
    learner="xgboost",  # Options: "xgboost", "catboost", "lightgbm"
    val_size=0.25,
    tree_params={"n_estimators": 100, "max_depth": 3},
    fit_params={"verbose": False}
)

# Evaluate model performance
scores = vaep.score(X_all, y_all)
print(f"Scoring model AUROC: {scores['scores']['auroc']:.3f}")
print(f"Conceding model AUROC: {scores['concedes']['auroc']:.3f}")

# Rate actions for a specific game
game = games.iloc[0]
game_series = pd.Series({"game_id": game.game_id, "home_team_id": game.home_team_id})
game_actions = all_actions[0]
ratings = vaep.rate(game_series, game_actions)
print(ratings[["offensive_value", "defensive_value", "vaep_value"]])
# Output:
#    offensive_value  defensive_value  vaep_value
# 0         0.002345        -0.001234    0.001111
# 1         0.001567         0.000234    0.001801
# 2         0.003456        -0.000567    0.002889

# Combine actions with VAEP values
game_actions_with_values = pd.concat([game_actions.reset_index(drop=True), ratings], axis=1)
print(game_actions_with_values[["player_id", "type_name", "vaep_value"]].head(10))
```

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

### Import Libraries and Configure Environment

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/3-estimate-scoring-and-conceding-probabilities.ipynb

Imports necessary Python libraries for data manipulation, warnings, progress bars, and machine learning. It also configures pandas to ignore performance warnings and sets up the autoreload extension for interactive development.

```python
import os
import warnings
import tqdm
import pandas as pd
warnings.simplefilter(action='ignore', category=pd.errors.PerformanceWarning)
```

```python
%load_ext autoreload
%autoreload 2
import socceraction.vaep.features as fs
import socceraction.vaep.labels as lab
```

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

### Initialize StatsBombLoader for Open Data

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/data/statsbomb.rst

Initializes the StatsBombLoader to fetch data from the StatsBomb Open Data repository. It configures the loader to use the 'remote' getter and sets credentials to None, as no authentication is required for open data.

```python
# optional: suppress warning about missing authentication
import warnings
from statsbombpy.api_client import NoAuthWarning
warnings.simplefilter('ignore', NoAuthWarning)

from socceraction.data.statsbomb import StatsBombLoader

api = StatsBombLoader(getter="remote", creds=None)
```

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

### SoccerAction Class Documentation

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/_templates/schema.rst

Documentation for the main class within the SoccerAction project.

```APIDOC
## SoccerAction Class

### Description
Provides detailed information about the SoccerAction class, its methods, and attributes.

### Method
N/A (Class Documentation)

### Endpoint
N/A (Class Documentation)

### Parameters
N/A (Class Documentation)

### Request Example
N/A (Class Documentation)

### Response
#### Class Structure
- **fullname** (string) - The full name of the class.
- **module** (string) - The module where the class is defined.
- **objname** (string) - The name of the object.

#### Attributes
- **attributes** (list) - A list of attributes associated with the class.

### Response Example
```
## SoccerAction

.. currentmodule:: socceraction.actions

.. autoclass:: socceraction.actions.SoccerAction

   .. rubric:: Attributes

   .. autosummary::
      :nosignatures:

     ~SoccerAction.action_type
     ~SoccerAction.start_time
     ~SoccerAction.end_time
     ~SoccerAction.player_id
     ~SoccerAction.team_id
     ~SoccerAction.x
     ~SoccerAction.y
```
```

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

### Load Wyscout Data (API or Local)

Source: https://context7.com/ml-kuleuven/socceraction/llms.txt

Provides functionality to load soccer data from Wyscout, supporting both remote API access and local JSON files. Configuration for feeds is flexible. Requires environment variables for API authentication.

```python
from socceraction.data.wyscout import WyscoutLoader
import os

# For API access, set credentials via environment variables
os.environ["WY_USERNAME"] = "your_username"
os.environ["WY_PASSWORD"] = "your_password"

# Initialize loader for API access
loader = WyscoutLoader(getter="remote")

# Or for local files with custom feed patterns
loader = WyscoutLoader(
    root="/path/to/wyscout/data",
    getter="local",
    feeds={
        "competitions": "competitions.json",
        "seasons": "seasons_{competition_id}.json",
        "games": "matches_{season_id}.json",
        "events": "matches/events_{game_id}.json",
    }
)

# Load competitions and games
competitions = loader.competitions()
games = loader.games(competition_id=524, season_id=181248)
events = loader.events(game_id=games.iloc[0].game_id)
```

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

### OptaLoader - Load Opta/Stats Perform Data

Source: https://context7.com/ml-kuleuven/socceraction/llms.txt

Supports various Opta feed formats including F1, F7, F9, F24, MA1, MA3, and WhoScored JSON files.

```APIDOC
## OptaLoader - Load Opta/Stats Perform Data

### Description
The OptaLoader supports various Opta feed formats including F1, F7, F9, F24, MA1, MA3, and WhoScored JSON files.

### Initialization (WhoScored Feed)
```python
from socceraction.data.opta import OptaLoader

loader = OptaLoader(
    root="/path/to/opta/data",
    parser="whoscored",  # Options: "whoscored", "f1", "f7", "f9", "f24", "ma1", "ma3"
    feeds={
        "whoscored": "whoscored/matches/{game_id}.json"
    }
)
```

### Initialization (Stats Perform MA3 Feed)
```python
from socceraction.data.opta import OptaLoader

loader = OptaLoader(
    root="/path/to/statsperform/data",
    parser="ma3",
    feeds={
        "ma3": "MA3_EPL_{game_id}.json"
    }
)
```

### Usage Examples
```python
# Load events for a specific game
events = loader.events(game_id=12345)
teams = loader.teams(game_id=12345)
players = loader.players(game_id=12345)
```
```

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

### Select Competitions and Seasons

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/ATOMIC-1-load-and-convert-statsbomb-data.ipynb

Loads available competitions and filters them based on competition name and season. This allows for targeted data retrieval for specific tournaments.

```python
# View all available competitions
competitions = SBL.competitions()
set(competitions.competition_name)

# Fifa world cup
selected_competitions = competitions[
    (competitions.competition_name == "FIFA World Cup")
    & (competitions.season_name == "2018")
]

# # Messi data
# selected_competitions = competitions[competitions.competition_name == "La Liga"]

# # FA Women's Super League
# selected_competitions = competitions[competitions.competition_name == "FA Women's Super League"]
selected_competitions
```

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

### Load Expected Threat (xT) model

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/intro.rst

Loads a pre-trained Expected Threat (xT) model from a specified URL. This model is used to quantify the threat level of different zones on a soccer pitch, which is essential for valuing actions.

```python
import socceraction.xthreat as xthreat

url_grid = "https://karun.in/blog/data/open_xt_12x8_v1.json"
xT_model = xthreat.load_model(url_grid)
```

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

### Load StatsBomb data using StatsBombLoader

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/documentation/intro.rst

Loads soccer match data from StatsBomb using the StatsBombLoader. It shows how to retrieve competition and game information, and then specific game details like teams, players, and events.

```python
import pandas as pd
from socceraction.data.statsbomb import StatsBombLoader

# Set up the StatsBomb data loader
SBL = StatsBombLoader()

# View all available competitions
df_competitions = SBL.competitions()

# Create a dataframe with all games from the 2018 World Cup
df_games = SBL.games(competition_id=43, season_id=3).set_index("game_id")

game_id = 8657
df_teams = SBL.teams(game_id)
df_players = SBL.players(game_id)
df_events = SBL.events(game_id)
```

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

### WyscoutLoader - Load Wyscout API or Local Data

Source: https://context7.com/ml-kuleuven/socceraction/llms.txt

Provides access to Wyscout data from the paid API or local JSON files with flexible feed configuration.

```APIDOC
## WyscoutLoader - Load Wyscout API or Local Data

### Description
The WyscoutLoader provides access to Wyscout data from the paid API or local JSON files with flexible feed configuration.

### Initialization (API Access)
```python
from socceraction.data.wyscout import WyscoutLoader
import os

# For API access, set credentials via environment variables
os.environ["WY_USERNAME"] = "your_username"
os.environ["WY_PASSWORD"] = "your_password"

# Initialize loader for API access
loader = WyscoutLoader(getter="remote")
```

### Initialization (Local Files)
```python
from socceraction.data.wyscout import WyscoutLoader

loader = WyscoutLoader(
    root="/path/to/wyscout/data",
    getter="local",
    feeds={
        "competitions": "competitions.json",
        "seasons": "seasons_{competition_id}.json",
        "games": "matches_{season_id}.json",
        "events": "matches/events_{game_id}.json",
    }
)
```

### Usage Examples
```python
# Load competitions and games
competitions = loader.competitions()
games = loader.games(competition_id=524, season_id=181248)
events = loader.events(game_id=games.iloc[0].game_id)
```
```

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

### Load and Convert Match Events to SPADL

Source: https://github.com/ml-kuleuven/socceraction/blob/master/public-notebooks/ATOMIC-1-load-and-convert-statsbomb-data.ipynb

Iterates through each game, loading team, player, and event data. It then converts the raw events into the SPADL (Soccer Players Actions) format, including atomic actions, and stores them in a dictionary keyed by game ID.

```python
games_verbose = tqdm.tqdm(list(games.itertuples()), desc="Loading game data")
teams, players = [], []
actions = {}
atomic_actions = {}
for game in games_verbose:
    # load data
    teams.append(SBL.teams(game.game_id))
    players.append(SBL.players(game.game_id))
    events = SBL.events(game.game_id)
    
    # convert data
    actions = spadl.statsbomb.convert_to_actions(
        events, 
        home_team_id=game.home_team_id,
        xy_fidelity_version=1,
        shot_fidelity_version=1
    )
    atomic_actions[game.game_id] = atomicspadl.convert_to_atomic(actions)

teams = pd.concat(teams).drop_duplicates(subset="team_id")
players = pd.concat(players)
```

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

### Data Loading Modules

Source: https://github.com/ml-kuleuven/socceraction/blob/master/docs/api/data.rst

Overview of the available data loading modules for different football data providers.

```APIDOC
## Data Loading Modules

### Description
The socceraction.data module provides standardized loaders for various football event data formats. These modules facilitate the ingestion of raw data into the library's internal structure.

### Available Modules
- **StatsBomb**: Handles loading of StatsBomb event data.
- **Opta**: Handles loading of Opta event data, including derived formats from Stats Perform and WhoScored.
- **Wyscout**: Handles loading of Wyscout event data.

### Usage
Each module is accessible via `socceraction.data.<provider>`. Please refer to the specific provider documentation for detailed class methods and parameters.
```