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
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.59.0.tar.gz.
File metadata
- Download URL: silly_kicks-4.59.0.tar.gz
- Upload date:
- Size: 18.6 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
081c9f2ccf95a76674eef325683419ad00b3e1a08da1dd4d60f0f8835c462c33
|
|
| MD5 |
0b8709f37d12508b2ffe9ce8c0d3ca2b
|
|
| BLAKE2b-256 |
f75da4b74a184885fed799e5afcee830105ebb1eba3a48d88d57ebd34129708c
|
Provenance
The following attestation bundles were made for silly_kicks-4.59.0.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.59.0.tar.gz -
Subject digest:
081c9f2ccf95a76674eef325683419ad00b3e1a08da1dd4d60f0f8835c462c33 - Sigstore transparency entry: 2234368069
- Sigstore integration time:
-
Permalink:
karsten-s-nielsen/silly-kicks@0fc41d7eddcb029fc20ac9f0511c6723578e85b5 -
Branch / Tag:
refs/tags/v4.59.0 - Owner: https://github.com/karsten-s-nielsen
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@0fc41d7eddcb029fc20ac9f0511c6723578e85b5 -
Trigger Event:
push
-
Statement type:
File details
Details for the file silly_kicks-4.59.0-py3-none-any.whl.
File metadata
- Download URL: silly_kicks-4.59.0-py3-none-any.whl
- Upload date:
- Size: 1.6 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
52c86caa14958959f29f56cea218f9fec1839435502531071b45d285da419a2a
|
|
| MD5 |
7aa62f6d5e5558cf0c05e0c63ebeba67
|
|
| BLAKE2b-256 |
0deea11d0909f3111be4c11e10d3563dbad4cccadfc3abaabf4961afd35b7a0d
|
Provenance
The following attestation bundles were made for silly_kicks-4.59.0-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.59.0-py3-none-any.whl -
Subject digest:
52c86caa14958959f29f56cea218f9fec1839435502531071b45d285da419a2a - Sigstore transparency entry: 2234368598
- Sigstore integration time:
-
Permalink:
karsten-s-nielsen/silly-kicks@0fc41d7eddcb029fc20ac9f0511c6723578e85b5 -
Branch / Tag:
refs/tags/v4.59.0 - Owner: https://github.com/karsten-s-nielsen
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@0fc41d7eddcb029fc20ac9f0511c6723578e85b5 -
Trigger Event:
push
-
Statement type:
