silly-kicks 1.0.0__tar.gz

silly_kicks-1.0.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @karsten-s-nielsen

silly_kicks-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug Report
+about: Report a bug in silly-kicks
+title: "[Bug] "
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To reproduce**
+```python
+# Minimal code to reproduce
+```
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- silly-kicks version:
+- Python version:
+- pandas version:
+- OS:
+
+**Additional context**
+Any other context (stack trace, data sample, etc.)

silly_kicks-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature Request
+about: Suggest a feature for silly-kicks
+title: "[Feature] "
+labels: enhancement
+---
+
+**Is this related to a problem?**
+A clear description of the problem. E.g., "I'm frustrated when..."
+
+**Proposed solution**
+Describe the solution you'd like.
+
+**Alternatives considered**
+Any alternative solutions or features you've considered.
+
+**Additional context**
+Any other context (links to papers, data examples, etc.)

silly_kicks-1.0.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

silly_kicks-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## Summary
+
+Brief description of what this PR does.
+
+## Changes
+
+- 
+
+## Testing
+
+- [ ] Tests pass (`pytest tests/ -m "not e2e"`)
+- [ ] Lint clean (`ruff check silly_kicks/ tests/`)
+- [ ] Types clean (`pyright silly_kicks/`)
+
+## Related issues
+
+Closes #

silly_kicks-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions: read-all
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - run: pip install ruff==0.15.7 pyright==1.1.395
+      - run: ruff check silly_kicks/ tests/
+      - run: ruff format --check silly_kicks/ tests/
+      - run: pip install -e ".[test]"
+      - run: pyright silly_kicks/
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+        exclude:
+          - os: windows-latest
+            python-version: "3.10"
+          - os: windows-latest
+            python-version: "3.11"
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[kloppy,xgboost,test]"
+      - run: pytest tests/ -m "not e2e" -v --tb=short

silly_kicks-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          print-hash: true

silly_kicks-1.0.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets and credentials
+.env
+.env.*
+*.key
+*.pem
+credentials.json
+
+# Downloaded test datasets (not committed)
+tests/datasets/statsbomb/
+tests/datasets/wyscout_public/
+
+# Claude Code
+.claude/

silly_kicks-1.0.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to silly-kicks will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-04-07
+
+### Added
+- DEBUG logging for kloppy silent event drops (aerial duels, unrecognized GK subtypes)
+- `.github/CODEOWNERS` for code owner review enforcement
+
+### Fixed
+- StatsBomb converter now accepts both `"goalkeeper"` and `"goal_keeper"` keys in the
+  extra dict — adapters that snake-case the event type name no longer silently lose all
+  keeper actions
+
+### Improved
+- `ConversionReport` docstring: full Attributes section, usage example, provider-specific
+  key type note
+- `add_names()` docstring: explicit guarantee that caller-added columns are preserved
+- `_finalize_output()` docstring: guarantee that all SPADL_COLUMNS are present
+- `config.py` docstring: `actiontype_id`, `result_id`, `bodypart_id` reverse dicts documented
+- Wyscout `convert_to_actions()`: Returns section now documents `ConversionReport`;
+  `goalkeeper_ids` notes `None` ≡ empty set equivalence
+
+### Removed
+- `docs/plans/` and `docs/specs/` — internal development artifacts with local paths
+
+### Changed
+- Version bump: 0.1.0 → 1.0.0 (Production/Stable)
+- C4 diagram genericized (removed project-specific references)
+
+## [0.1.0] — 2026-04-06
+
+### Added
+- Initial release as maintained successor to socceraction v1.5.3
+- SPADL converters: StatsBomb, Opta, Wyscout, Kloppy
+- VAEP and Atomic-VAEP frameworks
+- HybridVAEP — result-leakage-free action valuation
+- xG-targeted labels via `xg_column` parameter
+- Expected Saves (xS) label via `save_from_shot()`
+- Expected Claims (xC) label via `claim_from_cross()`
+- Cross zone feature (Gelade 2017 four-zone classification)
+- Assist type feature (through ball, cutback, cross, set piece, progressive pass)
+- Wyscout `goalkeeper_ids` parameter for GK aerial duel routing (#37)
+- `ConversionReport` audit trail for every conversion
+- `validate_spadl()` utility for DataFrame validation
+- Input validation with clear error messages per provider
+- "Nothing Left Behind" mapping registries (mapped/excluded/unrecognized events)
+- Reproducible training via `random_state` parameter
+
+### Changed (from socceraction v1.5.3)
+- Dropped pandera dependency — schemas are plain Python constants
+- Dropped multimethod dependency
+- Removed numpy<2.0 upper bound
+- All converters return `tuple[pd.DataFrame, ConversionReport]`
+- All `apply(axis=1)` hot paths replaced with `np.select` vectorization
+- Wyscout module decomposed into 3 files
+- Gamestates uses vectorized shift instead of `groupby().apply()`
+- Config DataFrame factories cached with `@functools.cache`
+- Labels vectorized (shift-based accumulation replaces 27-column loop)
+- `actiontype_result_onehot` uses numpy broadcasting
+
+### Fixed
+- Bug #507: Empty game crash in `gamestates()`
+- Bug #950: `actiontype` feature wrong for Atomic-SPADL
+- Bug #784: Opta converter silently drops card events
+- Bug #831: Atomic-SPADL missing "out" for blocked/saved shots
+- Bug #37/D44: Wyscout keeper_claim/punch differentiation
+- Bug #946: pandas 3.0 `fillna(inplace=True)` deprecation
+- pandas 3.0 `groupby().apply(as_index=False)` key column drop

silly_kicks-1.0.0/CLAUDE.md

@@ -0,0 +1,36 @@
+# silly-kicks
+
+Maintained fork of socceraction — SPADL event conversion + VAEP action valuation for soccer analytics.
+
+## Architecture
+
+- **Hexagonal**: All core functions are pure (pandas in, pandas out). Zero I/O, zero global state mutation.
+- **Converters** (`spadl/`): Each provider (StatsBomb, Opta, Wyscout, Kloppy) has its own module. All return `tuple[pd.DataFrame, ConversionReport]` with guaranteed columns/dtypes via `_finalize_output()`.
+- **VAEP** (`vaep/`): Feature engineering + gradient boosting binary classifiers. `HybridVAEP` removes result leakage from a0 features. xG-targeted labels available via `xg_column` parameter.
+- **Atomic-SPADL** (`atomic/`): Variant where actions are decomposed into atomic sub-actions (receival, interception, out, etc.).
+
+## Key conventions
+
+- No pandera — schemas are plain Python dicts (`SPADL_COLUMNS`, `ATOMIC_SPADL_COLUMNS`).
+- Config DataFrames (`actiontypes_df()`, etc.) are cached with `@functools.cache`.
+- Vectorized dispatch: converters use `np.select` over pre-flattened columns, not `apply(axis=1)`.
+- All `warnings.warn()` calls include `stacklevel=2`.
+- ML naming conventions (uppercase `X`, `Y`, `Pscores`) are allowed in `vaep/` and `xthreat.py` per ruff per-file-ignores.
+
+## Testing
+
+```bash
+python -m pytest tests/ -m "not e2e" -v --tb=short
+```
+
+e2e tests require dataset fixtures not committed to the repo.
+
+## Open Items
+
+See [TODO.md](TODO.md) for tracked work. Audit history in [docs/DEFERRED.md](docs/DEFERRED.md).
+
+## Dependencies
+
+- Runtime: pandas, numpy, scikit-learn (no pandera, no multimethod)
+- Optional: kloppy, xgboost, catboost, lightgbm
+- numpy>=2.0 compatible

silly_kicks-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers. All complaints will be reviewed and
+investigated and will result in a response that is deemed necessary and
+appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

silly_kicks-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to silly-kicks
+
+## Development Setup
+
+```bash
+git clone https://github.com/karsten-s-nielsen/silly-kicks.git
+cd silly-kicks
+pip install -e ".[kloppy,xgboost,test,dev]"
+```
+
+## Running Tests
+
+```bash
+# Unit tests (fast, no external data needed)
+python -m pytest tests/ -m "not e2e" -v
+
+# With coverage
+python -m pytest tests/ -m "not e2e" --cov=silly_kicks
+```
+
+## Code Quality
+
+```bash
+# Lint
+ruff check silly_kicks/ tests/
+ruff format silly_kicks/ tests/
+
+# Type check
+pyright silly_kicks/
+```
+
+## Pull Request Process
+
+1. Create a feature branch from `main`
+2. Write tests first (TDD preferred)
+3. Ensure all CI checks pass: `ruff check`, `ruff format --check`, `pyright`, `pytest`
+4. Keep commits focused — one logical change per commit
+5. Include a clear description of what and why
+
+## Architecture Guidelines
+
+- All core functions are pure: pandas in, pandas out
+- Converters return `tuple[pd.DataFrame, ConversionReport]`
+- Use `np.select` for vectorized dispatch, not `apply(axis=1)`
+- Add `stacklevel=2` to all `warnings.warn()` calls
+- New public functions need docstrings with Parameters/Returns sections

silly_kicks-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2019 KU Leuven Machine Learning Research Group - Tom Decroos, Pieter Robberechts
+Copyright (c) 2026 Karsten S. Nielsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

silly_kicks-1.0.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: silly-kicks
+Version: 1.0.0
+Summary: Classify and value on-ball football actions using SPADL and VAEP
+Project-URL: Homepage, https://github.com/karsten-s-nielsen/silly-kicks
+Project-URL: Repository, https://github.com/karsten-s-nielsen/silly-kicks
+Author: Karsten S. Nielsen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: SPADL,VAEP,actions,analytics,football,soccer
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas>=2.1.1
+Requires-Dist: scikit-learn>=1.3.1
+Provides-Extra: catboost
+Requires-Dist: catboost>=1.2; extra == 'catboost'
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: kloppy
+Requires-Dist: kloppy>=3.15.0; extra == 'kloppy'
+Provides-Extra: lightgbm
+Requires-Dist: lightgbm>=4.0; extra == 'lightgbm'
+Provides-Extra: test
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.11.1; extra == 'test'
+Requires-Dist: pytest>=7.4.2; extra == 'test'
+Provides-Extra: xgboost
+Requires-Dist: xgboost>=2.0.0; extra == 'xgboost'
+Description-Content-Type: text/markdown
+
+# silly kicks
+
+![The Modern SPADL Analyst vs The Chief SPADL Evaluator & Classifier](assets/silly-kicks.jpg)
+<sup>Comic by NanoBanana &mdash; inspired by Monty Python's <em>Ministry of Silly Walks</em></sup>
+
+[![CI](https://github.com/karsten-s-nielsen/silly-kicks/actions/workflows/ci.yml/badge.svg)](https://github.com/karsten-s-nielsen/silly-kicks/actions/workflows/ci.yml)
+
+*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](https://github.com/ML-KULeuven/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 converters for StatsBomb, Wyscout, Opta, and kloppy
+- **VAEP** -- Valuing Actions by Estimating Probabilities: a framework for
+  quantifying the value of individual actions
+- **Atomic SPADL** -- continuous (non-discretized) action representation
+
+## Installation
+
+```bash
+pip install silly-kicks
+```
+
+Requires Python 3.10 or later.
+
+With optional provider support:
+
+```bash
+pip install "silly-kicks[kloppy,xgboost]"
+```
+
+## Quick Start
+
+```python
+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.
+
+```python
+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.
+
+```python
+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.
+
+```python
+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`](docs/c4/architecture.html) in a browser to explore the C4 architecture diagrams (System Context, Containers).
+
+## Attribution
+
+This project 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:
+
+```bibtex
+@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](CONTRIBUTING.md) for development setup, coding standards,
+and PR process. Open items and planned work are tracked in [TODO.md](TODO.md).
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.