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). Two so far:
Sportec/DFL (behind the
[parse-dfl]extra), and StatsBomb SB360 freeze-frames → tracking frames +visible_areapolygons (no 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
Release files for silly-kicks 4.111.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| silly_kicks-4.111.0.tar.gz | 31.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| silly_kicks-4.111.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 43.6 MB
Release files / silly_kicks-4.111.0.tar.gz
| Download URL | silly_kicks-4.111.0.tar.gz |
|---|---|
| Size | 31.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2616c8f172fe39523ae1aeed596979b19f75de238f347739242762bd53e14519
|
|
BLAKE2b-256 checksum How to use checksums |
0cc972c2f10e0db1357e2ff081b74d522a741332bf9de2c0bb0341252e262a47
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / silly_kicks-4.111.0-py3-none-any.whl
| Download URL | silly_kicks-4.111.0-py3-none-any.whl |
|---|---|
| Size | 11.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f84e8552cf023c0ee65913a2c227c5ddfebf0c64a0f3d17633fc631adfe74905
|
|
BLAKE2b-256 checksum How to use checksums |
bf6bf09923666aa2fd41dbef2cae70612682c49fb7f19665bb81ab40966dd3a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency log
