football-core
Shared foundation for the football model repositories:
| Repo | Scope |
|---|
| football-core | Data loaders, canonical schema, pitch coordinates, plotting |
| football-shot-models | xG, xGOT / PSxG, goalkeeper shot-stopping |
| football-passing-models | xPass, xA, xGChain / xGBuildup, packing |
| football-possession-value | xT, VAEP, OBV / PV-style action valuation |
| football-tracking-models | Pitch control, EPV, OBSO, pressing intensity |
Status: built and tested: pitch (the piecewise provider mapping, goal mouth and goal
frame), schema (shots, freeze frames and the canonical matches table, each column tagged with
a leakage role), io.snapshot with the fc CLI, the StatsBomb open-data loader
io.statsbomb, the private WhoScored / Opta archive loader io.whoscored (git-ignored snapshot
and manifest), goalmouth with fc goalmouth, viz (the light and dark chart theme with
vendored Inter, the chart canvas and its machine checks) and football_docs (the docs-site
tooling: role rendering, page checks, theme, repository metadata check), with GitHub Actions
workflows for the checks and the docs site. Next: a maintenance round in
football-shot-models, the git dependency switch, then football-passing-models on the same core
and theme layer. See docs/roadmap.md and
docs/modules.md.
Why a shared package
Every model repo needs the same three things: read events from different providers, put them
on one pitch, and draw them. Doing that once keeps the model repos focused on modelling and
guarantees that a coordinate in one repo means the same thing in every other.
Conventions (summary)
- Coordinates: metres on a 105 x 68 pitch; the team in possession attacks towards
x = 105.
Provider grids are mapped piecewise between pitch markings, never scaled linearly.
- Data: scraped WhoScored data never leaves this machine; public work uses StatsBomb open data.
Full detail: docs/conventions.md, docs/data-policy.md.
Snapshots
Freeze a set of parquet tables and check later that they have not changed. Data goes to
data/snapshots/<name>/ (git-ignored); commit only manifests/<name>.json.
uv run fc snapshot demo --input exports/ # one table per .parquet file
uv run fc verify manifests/demo.json # exit 1 and the file name if anything changed
Run it as uv run fc (zsh and bash have a builtin fc) or as football-core. Details:
docs/api/snapshot.md.
StatsBomb open data is downloaded once into the git-ignored cache and frozen as a snapshot:
uv run fc snapshot statsbomb-open-v1 --builder statsbomb --input data/raw/statsbomb/open-data
Never commit or redistribute the data; every StatsBomb chart carries the StatsBomb logo
(docs/api/statsbomb.md, docs/api/viz.md).
Development
uv sync --all-groups
make check # ruff, mypy, pytest, strict docs build
make docs-serve # documentation site at http://127.0.0.1:8000
License
MIT. See LICENSE.
