luxury-lakehouse/football2vec-statsbomb-wyscout

Football2Vec v2 Embeddings — StatsBomb + Wyscout

Per-player 192-dimensional embeddings produced by Football2Vec v2 — a transformer encoder with adversarial competition debiasing. Trained on ~3,000 StatsBomb + ~1,900 Wyscout open-data matches; the dataset here is the post-training embeddings output, one row per unique canonical player.

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

Naming note

This dataset is named football2vec-statsbomb-wyscout to match the historical v1 model repo name. The v2 model weights live at luxury-lakehouse/football2vec-v2; the legacy v1 model at luxury-lakehouse/football2vec-statsbomb-wyscout is deprecated and kept only for traceability. The embeddings in this dataset come from v2; the repo name is retained for backward compatibility with downstream consumers that read embeddings from this path.

Quick Start

from datasets import load_dataset
import numpy as np

ds = load_dataset("luxury-lakehouse/football2vec-statsbomb-wyscout")
df = ds["train"].to_pandas()
print(f"{len(df):,} players, dim={len(df.loc[0, 'embedding'])}")

Explore interactively: Soccer Analytics App

Schema

Column	Type	Description
canonical_player_id	Int64	Cross-source-resolved canonical player identifier
player_name	string	Player display name at time of training
embedding	list<float32>	192-dimensional vector produced by Football2Vec v2
total_matches	Int64	Number of matches the player appeared in across both sources
data_sources	list<string>	Sources where the player has appearances (statsbomb, wyscout)

Schema Migration — Dual-Column Window (2026-04-25 → 2026-07-22)

PR 5b of the lakehouse Kimball migration (ADR-011) adds the BIGINT surrogate player_key to the underlying lakehouse marts that consume embeddings produced by this model. This dataset's payload is unchanged in PR 5b — the parquet files continue to ship canonical_player_id only. PR 8 (planned 2026-07-22) will add player_key to the payload in a backwards-compatible way and announce a sunset for canonical_player_id.

Recommended consumer behaviour during this window:

• No change required. Continue to read canonical_player_id from this dataset.
• If you maintain your own join to a dim_players clone, you may pre-compute player_key = xxhash64(provider || '|' || cast(player_id as string)) to align with the lakehouse Kimball convention ahead of the payload change.
• After 2026-07-22 the dataset will carry both columns for at least one HF dataset version, then canonical_player_id will be deprecated. Migrate at your convenience inside that window.

If you depend on this dataset and need extra notice before the column drop, open an issue on the lakehouse repo.

Training Provenance

• Producer model: luxury-lakehouse/football2vec-v2
• Training corpus: luxury-lakehouse/football2vec-training-data
• Adversarial debiasing: gradient-reversal against a competition-prediction head (Ganin et al. 2016) so embeddings encode player behaviour rather than league identity
• Publishing script: scripts/train_football2vec_v2.py

Use Cases

• Player similarity search: cosine similarity over embedding returns behaviourally similar players across competitions
• Counterfactual substitution ("what would Player X do in Team Y's possessions?"): input for downstream visual analytics
• Role clustering: UMAP / PCA projections reveal role archetypes decoupled from competition identity (v1 baselines tended to cluster by league; v2 does not)

Limitations

• Open data only: commercial datasets cover additional leagues and seasons
• Training-time snapshot: embeddings are recomputed only when the v2 model is retrained; between training runs, new players are absent from this dataset
• Position-agnostic: no role tag — downstream consumers apply role classifiers separately

License

CC-BY-NC 4.0 (inherited from Wyscout training-data licensing).

Companion Resources

Resource	Type	Description
Football2Vec v2 Model	Model	Transformer encoder that produced these embeddings
Football2Vec Training Data	Dataset	Upstream training corpus
Football2Vec v1 (deprecated)	Model	Legacy Doc2Vec model — superseded by v2
Football2Vec Player Embeddings	Dataset	Multi-granularity embeddings (career/season/per-match)

PR 7 changelog (2026-04-27)

PR 5b (2026-04-25) added Kimball surrogate FK player_key to the upstream gold mart. The HF model-companion dataset payload republish was deferred at PR 5b and is absorbed into PR 7's scope per feedback_hf_artifacts_in_scope_pr and project_kimball_pr8_scope_locked. Payload now carries player_key (BIGINT) alongside the legacy player_id and canonical_player_id columns during the 2026-07-22 dual-column window. PR 8 will sunset the legacy ID columns post-2026-07-22.