socceraction

socceraction is an open-source Python package designed to simplify soccer event stream data analysis. Its primary functions include:

• VAEP Implementation: Provides an implementation of the VAEP (Valuing Actions by Expected Possession) possession value framework.
• Data Loading: Includes API clients to load data from popular providers like StatsBomb, Wyscout, and Opta (Stats Perform).
• Data Conversion: Converts proprietary data formats from various providers into a common action-based data format called SPADL (Soccer Player Action Description Language), which standardizes preprocessing for subsequent analysis.

socceraction is a Python toolkit designed to quantify the value of individual soccer player actions using event stream data. The package provides four main functional areas:

1. Data Ingestion: API clients to load event stream data from major providers: StatsBomb, Wyscout, and Opta.
2. Data Standardization: Converters that transform proprietary provider formats into unified, expressive languages: SPADL and atomic-SPADL.
3. Expected Threat (xT): An implementation of the xT possession value framework.
4. VAEP & Atomic-VAEP: Implementations of the VAEP and Atomic-VAEP possession value frameworks.

Note: If you are following external video tutorials (e.g., from the Friends of Tracking series), be aware they may be based on version 0.2.0. You may need to adapt the code for the current version of the library.

Socceraction is a Python package designed to quantify the impact of individual soccer player actions using event stream data. It provides a pipeline to convert raw data into actionable player values.

Key components include:

• Data Loading: API clients to load event stream data from StatsBomb, Opta, Wyscout, Stats Perform, and WhoScored into unified Pandas DataFrames.
• Data Conversion: Converters to transform proprietary provider formats into SPADL and atomic-SPADL (unified, expressive languages for on-the-ball player actions).
• Possession Value Frameworks:
  • Expected Threat (xT): Implementation of the xT framework.
  • VAEP and Atomic-VAEP: Implementation of the VAEP and Atomic-VAEP frameworks for valuing actions.

The socceraction.data module provides specialized submodules for loading and processing event data from major football data providers. Depending on your data source, you should use the corresponding module:

• StatsBomb: Use for loading StatsBomb event data.
• Opta: Use for loading Opta event data, including derived formats used by Stats Perform and WhoScored.
• Wyscout: Use for loading Wyscout event data.

Atomic-SPADL is a variation of the SPADL format designed to treat every action as an independent, completed event. Unlike standard SPADL, which might treat a pass as a single action involving both an initiator and a receiver, Atomic-SPADL splits these into separate actions (e.g., a pass action for the giver and a receival action for the receiver).

This distinction allows for more precise analysis of the contributions of individual players. For example, if a pass is not successful, Atomic-SPADL uses specific action types like interception or out to describe the outcome, rather than a single combined action.

VAEP (Valuing Actions by Estimating Probabilities) evaluates the impact of player actions by assessing how they change the probability of scoring or conceding a goal in the short-term future (typically the next 10 actions).

An action's value is derived from two components:

1. Offensive Value: The change in scoring probability ($\Delta P_{\text{score}}$) resulting from an action.
2. Defensive Value: The change in conceding probability ($\Delta P_{\text{concede}}$) resulting from an action.

The total VAEP value of an action is calculated as the difference between its offensive and defensive values:

$V_{\text{VAEP}}(a_i) = \Delta P_{\text{score}}(a_{i}, t) - \Delta P_{\text{concede}}(a_{i}, t)$

Socceraction uses a tabular action-oriented data format. This differs from commercial event-based formats in two key ways:

1. Actions vs. Events: Socceraction focuses on actions (subsets of events that require a player to perform them, such as a pass) rather than all events (which might include non-player actions like the end of a game).
2. Uniform Attributes: Unlike many event stream formats, Socceraction stores the same attributes for every action. This consistency allows the data to be stored in a table, making it compatible with automatic analysis tools.

Socceraction implements two specific versions of this format:

• SPADL
• Atomic-SPADL

While socceraction provides a unified DataFrame-based model focused on on-the-ball events, kloppy is a more flexible object-based model.

Use kloppy if:

• You need to load data from a source not supported by socceraction.
• You require tracking data.
• Your analysis requires a more complete set of events beyond on-the-ball actions.

Use socceraction if:

• You want a streamlined, DataFrame-based workflow for on-the-ball event analysis.
• You are using supported providers like StatsBomb, Wyscout, or Opta.

When using getter="local", your data directory must follow the same hierarchy as the StatsBomb Open Data repository:

root
├── competitions.json
├── events
│   ├── <match_id>.json
│   └── ...
├── lineups
│   ├── <match_id>.json
│   └── ...
├── matches
│   ├── <competition_id>
│   │   └── <season_id>.json
│   │   └── ...
│   └── ...
└── three-sixty
    ├── <match_id>.json
    └── ...