Silly Kicks
The Ministry requires that all football actions be properly classified and valued.
silly-kicks is a Python library for objectively quantifying the impact of individual actions performed by football players using event stream data.
It is an independently maintained successor to socceraction, originally developed by Tom Decroos and Pieter Robberechts at KU Leuven. Built under the MIT license with full attribution preserved.
Features
- SPADL -- Soccer Player Action Description Language: a unified schema for on-ball actions with dedicated DataFrame converters for StatsBomb, Wyscout, Opta, Sportec / IDSSE Bundesliga, Metrica Sports, Gradient Sports, and SkillCorner — plus a kloppy gateway for raw-provider-data consumers (StatsBomb, Sportec, Metrica)
- Tracking -- 20-column long-form per-frame schema parallel to SPADL, with native adapters for Sportec / IDSSE Bundesliga, Gradient Sports, SkillCorner, and Metrica plus a kloppy gateway (Metrica + SkillCorner) for raw-TrackingDataset consumers. Key capabilities: action-to-frame linkage, frame preprocessing (smoothing, interpolation, velocities), GK identification, defensive-line geometry, ball-carrier inference, and 40+ tracking-aware action-context features for HybridVAEP integration including pitch control (Spearman / Fernández-Bornn / Voronoi), GK influence primitives (GKDV Layer 1), pressure (three published methods), pre-shot GK position/angles, pre-action movement, off-ball runs, line-break detection (threshold + Ward clustering), and team shape envelope. Full feature inventory in the CHANGELOG.
- VAEP -- Valuing Actions by Estimating Probabilities: a framework for quantifying the value of individual actions
- Atomic SPADL -- continuous (non-discretized) action representation
- xT -- Expected Threat with a pluggable transition family (Singh counts / KDE-smoothed) and value iteration on a variable-resolution grid, plus a held-out transition-NLL evaluator
- xT-GK -- goalkeeper-distribution value. v1 (
tracking/_xt_gk.py) is a parametric per-action metric whose RAV term consumes the bundledGkCompletionModel; v2 (xtgk/) is a pressure-stratified possession-value surfaceV(z, p)and the metric built on it - GKDV -- GK Deterrent Value: counterfactual valuation of keeper positioning against a league-average "ghost" keeper in the same frame state
- Causal -- a propensity-score matching harness (ATT/ATNT with Abadie-Imbens standard errors) used to validate feature claims rather than assert them. Adds no new dependency -- pure numpy/scikit-learn, no R -- which is not the same as dependency-free
- Feature glossary -- a machine-readable registry of every derived column the
library emits, CI-gated for completeness and linked to
NOTICEattributions - Providers -- raw-data parse ports (bytes → bronze → converter input). Currently one:
Sportec/DFL, behind the
[parse-dfl]extra - Calibration -- an Optuna harness that recommends tuned defaults and never changes library constants
Installation
pip install silly-kicks
Requires Python 3.10 or later.
With optional provider support:
pip install "silly-kicks[kloppy,xgboost]"
Quick Start
import silly_kicks.spadl as spadl
# Convert StatsBomb events to SPADL actions
actions, report = spadl.statsbomb.convert_to_actions(events, home_team_id=123)
# Add human-readable names
actions = spadl.add_names(actions)
VAEP Workflow
The full pipeline: convert provider events to SPADL, train a VAEP model, and rate individual actions.
from silly_kicks.spadl import statsbomb
from silly_kicks.vaep import VAEP
# 1. Convert provider events to SPADL
actions, report = statsbomb.convert_to_actions(
events_df, home_team_id=home_team_id,
xy_fidelity_version=2, shot_fidelity_version=2,
)
# 2. Train a VAEP model
model = VAEP(nb_prev_actions=3)
features = model.compute_features(game, actions)
labels = model.compute_labels(game, actions)
model.fit(features, labels, learner="xgboost", random_state=42)
# 3. Rate actions
ratings = model.rate(game, actions)
# Returns DataFrame with offensive_value, defensive_value, vaep_value
Hybrid-VAEP
Standard VAEP includes the action's result (success/fail) as a feature, which creates information leakage. HybridVAEP removes result information from the current action while preserving it for previous actions.
from silly_kicks.vaep import HybridVAEP
# HybridVAEP removes result leakage from current-action features
model = HybridVAEP(nb_prev_actions=3)
# Same fit/rate API as standard VAEP
Multi-Provider Support
All converters share the same output schema, so downstream code works identically regardless of the data provider.
from silly_kicks.spadl import opta, wyscout
actions_opta, _ = opta.convert_to_actions(opta_events, home_team_id)
actions_wyscout, _ = wyscout.convert_to_actions(wyscout_events, home_team_id)
Architecture
Open docs/c4/architecture.html in a browser to explore the C4 architecture diagrams (System Context, Containers).
Attribution
This project incorporates academic methodologies from the soccer-analytics literature. See NOTICE for full bibliographic citations and third-party library acknowledgements.
silly-kicks builds on the foundational research by the KU Leuven Machine Learning Research Group. If you use this library in academic work, please cite the original papers:
@inproceedings{Decroos2019VAEP,
title = {Actions Speak Louder than Goals: Valuing Player Actions in Soccer},
author = {Tom Decroos and Lotte Bransen and Jan Van Haaren and Jesse Davis},
booktitle = {Proceedings of the 25th ACM SIGKDD International Conference
on Knowledge Discovery \& Data Mining},
pages = {1851--1861},
year = {2019},
doi = {10.1145/3292500.3330758}
}
@inproceedings{Decroos2020AtomicSPADL,
title = {Interpretable Prediction of Goals in Soccer},
author = {Tom Decroos and Jesse Davis},
booktitle = {Proceedings of the AAAI-20 Workshop on Artificial Intelligence
in Team Sports},
year = {2020}
}
Contributing
See CONTRIBUTING.md for development setup, coding standards, and PR process. Open items and planned work are tracked in TODO.md.
License
MIT License. See LICENSE for details.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file silly_kicks-4.77.1.tar.gz.
File metadata
- Download URL: silly_kicks-4.77.1.tar.gz
- Upload date:
- Size: 19.8 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
afbc43c6f48816542c6bf78448619335f1b52e632bc8ed615cceaf4f1a40141b
|
|
| MD5 |
1e258cb9e1a09babc3da719f785be4f0
|
|
| BLAKE2b-256 |
c3759c2e8f342891cefac3899970c6cb8bec6fd6634892fccc3160db397ae6ae
|
Provenance
The following attestation bundles were made for silly_kicks-4.77.1.tar.gz:
Publisher:
publish.yml on karsten-s-nielsen/silly-kicks
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
silly_kicks-4.77.1.tar.gz -
Subject digest:
afbc43c6f48816542c6bf78448619335f1b52e632bc8ed615cceaf4f1a40141b - Sigstore transparency entry: 2395856331
- Sigstore integration time:
-
Permalink:
karsten-s-nielsen/silly-kicks@a29ae0f7db89c8195b14ed132d695a60bf4f8efc -
Branch / Tag:
refs/tags/v4.77.1 - Owner: https://github.com/karsten-s-nielsen
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@a29ae0f7db89c8195b14ed132d695a60bf4f8efc -
Trigger Event:
push
-
Statement type:
File details
Details for the file silly_kicks-4.77.1-py3-none-any.whl.
File metadata
- Download URL: silly_kicks-4.77.1-py3-none-any.whl
- Upload date:
- Size: 1.8 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
eb2b62c7140b4b56ff13cdcc14f9207cefa9bd3b1612841e147720f8bb8edf53
|
|
| MD5 |
ef1a63e913fa28a9beeea9b8cac5f152
|
|
| BLAKE2b-256 |
5147f2376bd5638a38c4db8c9653ede59a886a7c8397132afc3df26c20f8b7ab
|
Provenance
The following attestation bundles were made for silly_kicks-4.77.1-py3-none-any.whl:
Publisher:
publish.yml on karsten-s-nielsen/silly-kicks
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
silly_kicks-4.77.1-py3-none-any.whl -
Subject digest:
eb2b62c7140b4b56ff13cdcc14f9207cefa9bd3b1612841e147720f8bb8edf53 - Sigstore transparency entry: 2395857040
- Sigstore integration time:
-
Permalink:
karsten-s-nielsen/silly-kicks@a29ae0f7db89c8195b14ed132d695a60bf4f8efc -
Branch / Tag:
refs/tags/v4.77.1 - Owner: https://github.com/karsten-s-nielsen
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@a29ae0f7db89c8195b14ed132d695a60bf4f8efc -
Trigger Event:
push
-
Statement type:
