This repository presents exPress (Explainable & Expected Press), a framework for quantifying pressing situations in football by analyzing individual player positioning and movements
git clone https://github.com/leemingo/sr-press.git
cd sr-press
pip install -r requirements.txt
- This project was developed using Python 3.9.20.
- Install the necessary libraries:
- To use the latest version of the socceraction library, you need to clone it directly from GitHub because it cannot be updated through standard installation methods.
- Since only the socceraction package is required, set socceraction/socceraction as the root directory and remove all other unnecessary files.
git clone https://github.com/statsbomb/open-data.git
git clone https://github.com/ML-KULeuven/socceraction.git- To access the data, navigate to the notebook.
- 1-load-and-convert-statsbomb-data.ipynb: Load the StatsBomb dataset and build the training dataset. Estimated time: 8 minutes.
- 2-computing-and-storing-features.ipynb: Extract features and labels from the built dataset. Estimated time: 27 minutes.
- The data is stored in the stores directory.
- The stores directory contains the features and labels, but due to storage limitations, not all features have been processed and included here.
🗂️ stores
├── 📄 train_database.sqlite # Database for training data
├── 📄 test_database.sqlite # Database for testing data
├── 🗂️ model # Directory for storing trained models
└── 🗂️ datasets # Directory containing feature and label datasets
├── 🗂️ train
│ ├── 📄 x_actiontype_onehot.parquet
│ ├── 📄 x_ball_height_onehot.parquet
│ ├── 📄 x_extract_all_players.parquet
│ ├── 📄 x_speed.parquet
│ ├── 📄 ...
│ └── 📄 y_counterpress.parquet
└── 🗂️ test
├── 📄 x_actiontype_onehot.parquet
├── 📄 x_ball_height_onehot.parquet
├── 📄 x_extract_all_players.parquet
├── 📄 x_speed.parquet
├── 📄 ...
└── 📄 y_counterpress.parquet
- databases: Data access and SPADL conversion (implemented _fix_pressure in base.py).
- features, labels: Define features and labels.
- component: Train the exPress model.
- simulates.py: Predict xP based on various position changes.
- Once the features and labels are stored in the stores directory, you can perform training using the following steps:
- 3-evaluating-model-performance.ipynb: : Analyze the results of the training performed using train.py
Training the XGBoost Model
python train.py \
--model xgboost \
--trial 0 \
--params_file params.json \
--nb_prev_actions 3 \
--xfns "startlocation" "closest_11_players" \
--yfns "counterpress"
Training SoccerMap Model
python train.py \
--model soccermap \
--trial 1 \
--params_file params.json \
--nb_prev_actions 3 \
--xfns "startlocation" "freeze_frame_360" \
--yfns "concede_shots"
please consider citing the following papers:
- Minho Lee, Geonhee Jo, Miru Hong, Pascal Bauer, and Sang-Ki Ko. Contextual Valuation of Individual Players Within Pressing Situations in Football. In 2025 MIT Sloan Sports Analytics Conference.
[ paper | github ]
This research is conducted by Korea AI Research Society for Sports (KAISports).