luxury-lakehouse/xg-freeze-frame-data

--- language: [en] license: cc-by-4.0 task_categories: - tabular-classification tags: - sports-analytics - soccer - football - expected-goals - freeze-frames - statsbomb - deep-sets size_categories: - 10M<n<100M configs: - config_name: default data_files: - split: train path: "data/**/*.parquet" --- # xG Freeze-Frame Data &mdash; StatsBomb 360 **~15.58M freeze-frame rows** from 323 StatsBomb 360 matches, capturing player positions at the moment of each shot. Each row represents one visible player in one shot event. Part of the (Right! Luxury!) Lakehouse soccer analytics platform. ## Quick Start ```python from datasets import load_dataset ds = load_dataset("luxury-lakehouse/xg-freeze-frame-data") df = ds["train"].to_pandas() # Average number of visible players per shot df.groupby("event_id").size().describe() ``` > **Explore interactively:** [Soccer Analytics App](https://huggingface.co/spaces/luxury-lakehouse/soccer-analytics-app) ## What Is This Dataset? StatsBomb 360 data includes inline freeze frames for each event &mdash; a snapshot of every visible player's position at the instant of the event. This dataset extracts freeze-frame rows specifically for shot events, providing the spatial context that the [xG v2 set encoder](https://huggingface.co/luxury-lakehouse/xg-v2-model-set-encoder) uses to condition expected goals predictions on defensive positioning. Each row represents one player visible in one shot. A single shot typically has 10&ndash;22 freeze-frame rows (one per visible player). The set encoder aggregates these into a fixed-length context vector using permutation-invariant sum pooling. ## Schema | Column | Type | Description | |--------|------|-------------| | `event_id` | `string` | Shot event ID (FK to xG Shot Data) | | `match_id` | `bigint` | Match identifier | | `competition_id` | `bigint` | Competition identifier | | `season_id` | `bigint` | Season identifier | | `player_x_norm` | `double` | Player x position normalized to [0, 1] from StatsBomb 120-yard pitch | | `player_y_norm` | `double` | Player y position normalized to [0, 1] from StatsBomb 80-yard pitch | | `is_keeper` | `boolean` | Whether the player is the goalkeeper | | `is_teammate` | `boolean` | Whether the player is on the shooting team | ### Coordinate System Raw positions are in the **StatsBomb coordinate system** (120 &times; 80 yards, origin at bottom-left, attacking direction left to right). The `player_x_norm` and `player_y_norm` columns are normalized: ``` x_norm = location_x / 120.0 y_norm = location_y / 80.0 ``` ## Data Sources | Source | Coverage | License | |--------|----------|---------| | [StatsBomb Open Data](https://github.com/statsbomb/open-data) (360 subset) | ~323 matches with inline freeze frames | CC-BY 4.0 | Only StatsBomb 360 matches include freeze-frame data. Non-360 StatsBomb matches and all Wyscout matches do not contribute to this dataset. The xG v2 model handles missing freeze frames by falling back to a zero context vector. ## Companion Resources | Resource | Type | Description | |----------|------|-------------| | [xG v2 Set Encoder](https://huggingface.co/luxury-lakehouse/xg-v2-model-set-encoder) | Model | Deep Sets encoder + MLP that consumes this dataset as spatial context | | [xG Shot Data](https://huggingface.co/datasets/luxury-lakehouse/xg-shot-data) | Dataset | Tabular shot features (joins on `event_id`) | | [xG Model v1](https://huggingface.co/luxury-lakehouse/xg-model-statsbomb-wyscout) | Model | Tabular-only XGBoost baseline (no freeze-frame context) | ## Limitations - **Partial visibility**: StatsBomb 360 captures only *visible* players. Players behind the camera or in crowded areas may be absent. The set encoder handles this gracefully (fewer rows per shot), but predictions may underestimate defensive pressure when defenders are occluded. - **StatsBomb 360 only**: Covers ~323 of ~3,000 StatsBomb matches. The majority of shots in the xG Shot Data dataset do not have corresponding freeze-frame rows. - **Shot events only**: This dataset extracts freeze frames for shots specifically. Freeze frames for other event types (passes, tackles) are not included. - **No player identity**: The dataset includes spatial position and role flags only. Player name, jersey number, height, and other attributes are not captured. ## Citation If you use this dataset, please cite StatsBomb and the Deep Sets architecture: ```bibtex @misc{statsbomb2024opendata, title={StatsBomb Open Data}, author={{StatsBomb}}, year={2024}, url={https://github.com/statsbomb/open-data}, note={CC-BY 4.0} } ``` ```bibtex @inproceedings{zaheer2017deep, title={Deep Sets}, author={Zaheer, Manzil and Kottur, Satwik and Ravanbakhsh, Siamak and P{\'o}czos, Barnab{\'a}s and Salakhutdinov, Ruslan and Smola, Alexander J.}, booktitle={Advances in Neural Information Processing Systems (NeurIPS)}, volume={30}, year={2017} } ``` ## More Information - **License**: [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) - **Publishing script**: `scripts/publish_xg_shots_hf.py` - **Platform**: [Luxury Lakehouse Soccer Analytics](https://github.com/karsten-s-nielsen/luxury-lakehouse) ## PR 7 changelog (2026-04-27) The lineage mart `fct_shots` now carries Kimball surrogate FKs (`team_key`, `player_key`) alongside the existing `match_key` (PR 3) and the legacy `team_id`/`player_id` INT columns during the 2026-07-22 dual-column window per ADR-011. The freeze-frame payload itself is unchanged at this grain; the keys flow through `fct_xg_predictions_v2` (the v2 set-encoder mart) via INNER JOIN to `fct_shots`. PR 8 will sunset legacy IDs post-2026-07-22.This dataset contains ~15.58M freeze-frame rows from 323 StatsBomb 360 matches, capturing player positions at the moment of each shot. Each row represents one visible player in one shot event. The dataset is primarily used to provide spatial context for the xG v2 set encoder to condition expected goals predictions. It includes normalized player position coordinates (x and y normalized to [0,1]), whether the player is a goalkeeper, and whether the player is a teammate. The data is sourced from the StatsBomb Open Data 360 subset and is licensed under CC-BY 4.0. The dataset also notes limitations such as partial player visibility, coverage of only a subset of matches, and inclusion of only shot events.

搜集汇总

数据集介绍

构建方式

围绕足球预期进球模型对防守站位信息的需求，该数据集的构建根植于StatsBomb 360开放数据生态。其原始素材为323场包含内联冻结帧的StatsBomb 360比赛，制作者从射门事件中抽取每个可见球员的瞬时位置，形成约1558万行冻结帧记录。每条记录以event_id锚定一次射门，并保留match_id、competition_id、season_id等赛事标识，同时将StatsBomb 120×80码坐标系下的x、y位置线性归一化至[0,1]，并附加is_keeper与is_teammate角色标记。发布形态为Parquet文件，默认train划分，便于集合式建模直接读取。

特点

立足于足球空间情境建模的粒度和可见性约束，该数据集呈现出集合化、部分观测与射门事件专属性等特征。每次射门通常对应10至22行球员记录，每行仅刻画一名可见球员的位置与角色，不包含姓名、球衣号或身体属性，因而天然适合以排列不变方式处理。StatsBomb 360仅覆盖约323场比赛，且冻结帧仅针对射门事件，非360比赛及其他事件类型不纳入其中。可见球员可能因遮挡而缺失，数据集本身不修正该偏差，配套模型以零上下文向量回退处理缺失冻结帧。

使用方法

面向预期进球预测与空间上下文编码任务，该数据集可通过Hugging Face datasets库便捷载入。典型流程为调用load_dataset("luxury-lakehouse/xg-freeze-frame-data")，将train划分转为pandas数据框，并按event_id分组以考察每次射门的可见球员数量。以event_id为外键与xG Shot Data连接后，可将冻结帧行输入xG v2 Set Encoder，借助置换不变求和池化聚合为固定长度上下文向量，并与射门表格特征融合以估计xG。若某次射门无对应冻结帧，则采用零上下文向量作为回退。

背景与挑战

背景概述

面向足球预期进球建模，xg-freeze-frame-data 将 StatsBomb 360 公开数据中的射门瞬间冻结帧转化为行级表格，为空间上下文学习提供基础。该数据集由 Luxury Lakehouse 足球分析平台构建，数据源为 StatsBomb Open Data，遵循 CC-BY 4.0 许可，并援引 Zaheer 等 2017 年 Deep Sets 架构。README 未明确首次创建日期，仅列有 2026-04-27 的变更记录；其核心研究问题是在 xG 预测中纳入每脚射门时可见球员的位置与角色，使集合编码器能够以排列不变方式聚合 10 至 22 名球员的防守站位。数据涵盖约 323 场 StatsBomb 360 比赛、约 1558 万冻结帧行，推动了足球分析从纯表格特征向集合式空间建模的拓展。

当前挑战

在足球事件数据驱动的预期进球估计中，xg-freeze-frame-data 所对应的领域问题是如何刻画射门瞬间的防守压力与空间结构；传统表格模型难以直接处理可变数量、无序排列的球员集合，而冻结帧仅捕获可见球员，遮挡或拥挤区域中的防守者可能缺失，进而低估防守强度。构建层面的挑战同样显著：StatsBomb 360 仅覆盖约 323 场、占其公开比赛的小部分，绝大多数射门缺少对应冻结帧；数据仅抽取射门事件，不含传球、抢断等其他事件；且不提供球员身份、号码、身高等个体属性。处理缺失冻结帧时需回退至零上下文向量，行级数据亦须严格关联 event_id、归一化至 [0,1] 坐标并遵守 CC-BY 4.0 许可，这些均对可复现分析与模型泛化构成约束。

常用场景

经典使用场景

在足球预期进球建模日益倚重空间情境的背景下，xg-freeze-frame-data的经典用途在于为射门事件提供球员位置集合表征。该数据集从323场StatsBomb 360比赛抽取约1558万条冻结帧记录，每一行对应当次射门瞬间一名可见球员，单次射门通常涵盖10至22名球员。研究者可依event_id聚合这些行，将player_x_norm、player_y_norm、is_keeper与is_teammate作为集合元素输入Deep Sets编码器，经置换不变池化生成固定长度上下文向量，并与xG Shot Data的表格特征融合，用于进球概率的表格分类。此流程尤其适合处理变长、无序且存在缺失的球员集合，构成当代xG建模的典型范式。

解决学术问题

就学术研究而言，传统xG模型长期依赖射门距离、角度、身体部位与助攻方式等表格变量，难以系统刻画防守压力、门将站位与队友牵制等空间结构，容易产生遗漏变量偏误。xg-freeze-frame-data以射门瞬间可见球员的坐标与角色标记，为集合型输入提供可复现的数据基础，使置换不变神经网络、变长集合学习及缺失情境下的鲁棒推断成为可检验问题。它推动xG研究从孤立射门特征转向关系型空间上下文，为防守组织评估、射门质量分解和模型可解释性提供新证据，对体育计量与机器学习交叉领域具有方法学意义。

衍生相关工作

围绕该数据集，衍生工作集中体现在xG v2 Set Encoder及其配套资源上。该编码器采用Deep Sets架构与MLP，消费xg-freeze-frame-data生成的球员集合，将空间上下文注入预期进球预测，并同xG Shot Data及仅使用表格特征的xG Model v1 XGBoost基线形成对照。方法源头可追溯至Zaheer等提出的Deep Sets，其置换不变聚合为该数据集处理变长球员集合提供理论支撑。这些工作共同构成Luxury Lakehouse足球分析平台中的xG v2管线，也为后续冻帧增强模型、防守压力指标与集合学习在体育分析中的拓展奠定基础。