Silly Kicks

The Modern SPADL Analyst vs The Chief SPADL Evaluator & Classifier ^{Comic by NanoBanana — inspired by Monty Python's Ministry of Silly Walks}

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

silly_kicks-4.68.0.tar.gz (18.9 MB view details)

Uploaded Jul 29, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

silly_kicks-4.68.0-py3-none-any.whl (1.6 MB view details)

Uploaded Jul 29, 2026 Python 3

File details

Details for the file silly_kicks-4.68.0.tar.gz.

File metadata

Download URL: silly_kicks-4.68.0.tar.gz
Upload date: Jul 29, 2026
Size: 18.9 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for silly_kicks-4.68.0.tar.gz
Algorithm	Hash digest
SHA256	`17700bac5ef9fca7f5fde62221a50a253810ec7deca6e7581a9da5ef9584e8b0`
MD5	`734f78892b09632aeb052391201c085b`
BLAKE2b-256	`5459b59d3f86ead89bcf08dd6e1f3ca0591f0efbd07c976d874867a56929b7e7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for silly_kicks-4.68.0.tar.gz:

Publisher: publish.yml on karsten-s-nielsen/silly-kicks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: silly_kicks-4.68.0.tar.gz
- Subject digest: 17700bac5ef9fca7f5fde62221a50a253810ec7deca6e7581a9da5ef9584e8b0
- Sigstore transparency entry: 2280918650
- Sigstore integration time: Jul 29, 2026
Source repository:
- Permalink: karsten-s-nielsen/silly-kicks@894458a83bbe8980b607ea7135f72cb4683ebc62
- Branch / Tag: refs/tags/v4.68.0
- Owner: https://github.com/karsten-s-nielsen
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@894458a83bbe8980b607ea7135f72cb4683ebc62
- Trigger Event: push