socceraction turns provider event streams into SPADL and then into action values

One action language on top of five provider formats

The problem the package addresses is that event data in soccer arrives in incompatible shapes. The README describes socceraction as a Python package for objectively quantifying the impact of the individual actions performed by soccer players using event stream data, with the general idea being to assign a value to each on-the-ball action based on its impact on the game outcome while accounting for the context in which the action happened. The pipeline has three stages, and each is a separate component. First, API clients load event stream data from StatsBomb, Opta, Wyscout, Stats Perform and WhoScored as Pandas DataFrames using a unified data model. Second, converters turn each provider's proprietary format into SPADL and atomic-SPADL, described as unified and expressive languages for on-the-ball player actions. Third, the value models run. The value of this design is that the SPADL layer is the contract, so a model trained on one provider's data can be applied to another without rewriting the feature layer.

xT, VAEP and the atomic variant

The action values come from two possession value frameworks, both implemented in the package. The first is Expected Threat, xT, whose original introduction the README credits to Karun Singh on his blog in 2019. The second is VAEP, the Valuing Actions by Estimating Probabilities framework, along with an Atomic-VAEP implementation. The distinction between xT and VAEP is the subject of one of the two papers the project asks you to cite, and the comparison is the point of the package rather than an implementation detail. xT is a per-location model, and VAEP models the value of actions in a state space of locations and other game state variables, with the atomic version breaking an action down into its constituent parts. If you are going to build features on top of this, choosing between them is a research decision, and the package supports both so that the comparison can be reproduced rather than argued about.

Installing it, and the extras that decide what you can load

Installation is a single pip command, and the supported interpreter range is stated plainly:

$ pip install socceraction

The latest version officially supports Python 3.9 to 3.12. The core dependencies are pandas, numpy, scikit-learn, lxml and pandera, and pandera is there for data validation, which for a package whose whole job is turning messy event feeds into a consistent table is not an optional detail. The optional extras are where the provider support lives. There is a `statsbomb` extra pulling in statsbombpy, an `xgboost` extra for gradient boosting models, an `hdf` extra for the tables package, and a `kloppy` extra for another event data toolkit. A team working only with Wyscout or Opta data installs the base package and nothing else, which keeps the dependency surface small, and a team training a boosting model adds the xgboost extra deliberately.

The notebooks and the Makefile show the intended workflow

The README points at a `public-notebooks` folder as a demo of the full pipeline from raw StatsBomb event stream data to action values and player ratings, with more detailed instructions in the documentation on Read the Docs. The Makefile shows how the maintainers run the project. The `init` target creates a virtual environment and runs a Poetry install, the `test` target first downloads and converts the StatsBomb, Wyscout public and SPADL test datasets and then runs the nox test session, and there are separate targets for mypy, lint and pre-commit. The `notebooks` target executes the public notebooks in place with nbconvert, which is the detail worth copying, because a notebook that only runs in its author's environment is not a reproducible artefact.

The project says it is not actively developed

This is the sentence that should shape your decision. The contributing section says all contributions, bug reports, fixes, documentation improvements and ideas are welcome, but warns that socceraction is not actively developed, that its primary use is to enable reproducibility of their research, and that if you believe a feature is missing you may raise a request but should be aware that the overwhelming likelihood is that it will not be accepted. There is also a developer guide in the documentation. The releases reflect that posture, with 1.5.1 in March 2024, 1.5.2 in June 2024 and 1.5.3 in August 2024, while the last push to the repository was on 2026-10-18. So the code is still moving, and the package version in the manifest is 1.5.3, but nobody is on the hook for your feature request. That is a perfectly reasonable arrangement for a research artefact and a poor one for a product dependency.

Licence, citation and where the funding came from

The licence is MIT, distributed under those terms, and the README adds that although it is not strictly required, the maintainers appreciate a link to the repository or a citation of their research if you use the package. Two papers are named. The first is Actions speak louder than goals: Valuing player actions in soccer, by Tom Decroos, Lotte Bransen, Jan Van Haaren and Jesse Davis, in the proceedings of the 25th ACM SIGKDD International Conference on Knowledge Discovery and Data Mining, with a pdf and a bibtex file linked. The second is Valuing on-the-ball actions in soccer: a critical comparison of XT and VAEP, by Maaike Van Roy, Pieter Robberechts, Tom Decroos and Jesse Davis, from the AAAI-20 Workshop on Artificial Intelligence in Team Sports, also with a bibtex. The acknowledgements section states that funding came from the Flemish Government under the Onderzoeksprogramma Artificiële Intelligentie, AI Vlaanderen programme, and the manifest lists the authors as Tom Decroos and Pieter Robberechts of KU Leuven.

Editorial conclusion

Adopt socceraction when your research needs a reproducible pipeline from raw provider event data to action values, since the package ships the provider clients, the SPADL conversion and the xT and VAEP implementations in one place, with a public notebook that demonstrates the whole flow. Do not adopt it expecting an actively developed library, because the README says plainly that the project is not actively developed and that its primary use is to enable reproducibility of their research, and that feature requests are unlikely to be accepted. Verify first that your provider's data and the Python version you need are supported, since the latest release officially supports Python 3.9 to 3.12, and check which optional extras your data source requires before you install.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. ML-KULeuven/socceraction on GitHub
4. README
5. Releases