luxury-lakehouse/spadl-vaep-action-values

SPADL/VAEP Action Values

Every on-ball action from ~9.5 million professional soccer events, converted to the SPADL unified format and scored with offensive, defensive, and net VAEP values. Built with the silly-kicks library — enabling player ranking by total contribution beyond goals and assists.

Part of the (Right! Luxury!) Lakehouse soccer analytics platform.

⚠️ Schema change (cut-over 2026-07-22)

This dataset now emits both legacy and canonical Kimball key columns side-by-side. The legacy columns will be removed on 2026-07-22 (90-day dual-column window opened at the PR 4b ship on 2026-04-24, per ADR-011):

Both columns are populated during the window. Update consumer code to read the canonical match_key / competition_key columns before the cut-over date; after cut-over the legacy columns are removed.

Quick Start

from datasets import load_dataset

ds = load_dataset("luxury-lakehouse/spadl-vaep-action-values")
df = ds["train"].to_pandas()

# Top 10 players by total VAEP contribution
top_players = df.groupby("player_id")["vaep_value"].sum().nlargest(10)

Explore interactively: Soccer Analytics App

What is SPADL/VAEP?

SPADL (Soccer Player Action Description Language) is a unified event representation that converts vendor-specific event streams into 23 canonical action types with standardized coordinates (105×68 meters). This enables cross-source analysis that would otherwise require bespoke adapters per data provider.

VAEP (Valuing Actions by Estimating Probabilities) scores each action by its impact on scoring and conceding probabilities, as described in:

Decroos, T., Bransen, L., Van Haaren, J., & Davis, J. (2019). Actions Speak Louder than Goals: Valuing Player Actions in Soccer. Proceedings of the 25th ACM SIGKDD International Conference on Knowledge Discovery & Data Mining.

Data Fields

Coordinate System

All coordinates use the SPADL academic standard: 105×68 meters representing real-world pitch dimensions. The origin (0, 0) is at the bottom-left corner of the attacking team's half. The x-axis runs along the length of the pitch (0–105m), and the y-axis runs along the width (0–68m).

Action Type Vocabulary

SPADL defines 23 canonical action types:

pass, cross, throw_in, freekick_crossed, freekick_short, corner_crossed, corner_short, take_on, foul, tackle, interception, shot, shot_penalty, shot_freekick, keeper_save, keeper_claim, keeper_punch, keeper_pick_up, clearance, bad_touch, non_action, dribble, goalkick

Data Sources

Partitioned by data_source (data/data_source=<provider>/data.parquet):

Coverage includes the Premier League, La Liga, Serie A, Bundesliga, Ligue 1, Champions League, World Cup, and more. One additional provider (GradientSports / PFF FC, FIFA World Cup 2022) is computed internally but license-restricted and therefore not included in this public dataset.

Limitations

• —Open data only: Built from publicly available event data. Commercial datasets with richer event annotations may yield different VAEP scores.
• —No tracking data: VAEP is event-based. Off-ball positioning, pressing intensity, and space creation are not captured.
• —Competition-agnostic model: The underlying XGBoost model is trained across all competitions jointly. League-specific models may produce more calibrated probabilities.
• —Cross-source alignment: Providers use different event taxonomies. The SPADL adapter normalizes them, but subtle differences in event definitions (e.g., duel classification) remain.

Citation

If you use this dataset, please cite the original VAEP paper:

@inproceedings{decroos2019actions,
  title={Actions Speak Louder than Goals: Valuing Player Actions in Soccer},
  author={Decroos, Tom and Bransen, Lotte and Van Haaren, Jan and Davis, Jesse},
  booktitle={Proceedings of the 25th ACM SIGKDD International Conference on Knowledge Discovery and Data Mining},
  pages={1851--1861},
  year={2019},
  publisher={ACM}
}

And the silly-kicks library:

@article{silly-kicks,
  title={silly-kicks: A Python library for valuing soccer actions},
  author={Decroos, Tom and Van Haaren, Jan and Davis, Jesse},
  year={2020},
  url={https://github.com/karsten-s-nielsen/silly-kicks}
}

Companion Resources

More Information

Explore interactively: Soccer Analytics App

ADR-049 changelog (2026-06-10)

The dataset is now published via the restricted-split mechanism (lakehouse ADR-049): the publisher pulls all providers from the gold mart and routes license-restricted partitions (currently GradientSports) to a private companion repo, with everything else published here. The partition layout is data/data_source=<provider>/data.parquet; legacy stray Parquet files inside partition directories were swept in the same change — glob data/*/data.parquet, not **/*.parquet. The schema also gains result_source (provenance tier of action_result, silly-kicks 4.21+; see Data Fields).

PR 7 changelog (2026-04-27)

The upstream gold mart fct_action_values (9.5M-row VAEP spine) now carries Kimball surrogate FKs (team_key, player_key) alongside the existing match_key (PR 4b) and the legacy team_id/player_id INT columns during the 2026-07-22 dual-column window per ADR-011. SPADL covers SB+WS providers only; native team/player IDs are real BIGINTs cast to string for the dim JOINs. PR 8 will sunset the legacy *_id columns post-2026-07-22.

• —License: MIT