openstarlab-phaselearn 0.0.2
openstarlab phaselearn modeling package
License: Apache License 2.0
Requires Python: >=3.8

# OpenSTARLab PhaseLearn Modeling package
[![Documentation Status](https://readthedocs.org/projects/openstarlab/badge/?version=latest)](https://openstarlab.readthedocs.io/en/latest/?badge=latest)
[![dm](https://img.shields.io/pypi/dm/openstarlab-phaselearn)](https://pypi.org/project/openstarlab-phaselearn/)
[![ArXiv](https://img.shields.io/badge/ArXiv-2502.02785-b31b1b?logo=arxiv)](https://arxiv.org/abs/2502.02785)
[![Discord](https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/PnH2MDDaCf)

## Introduction
The OpenSTARLab PhaseLearn package is the fundamental library for modeling and analyzing play phases in sports. It provides a robust framework to train and perform inference on play phases using state-of-the-art spatio-temporal architectures.

### Key Concepts
- [Definition of Play Phase](https://openstarlab.readthedocs.io/en/latest/PhaseLearn_Modeling/Sports/Soccer/phase.html): The estimation targets are **Phases of Play** as defined by FIFA.
- This package supports data preprocessed by the [OpenSTARLab PreProcessing package](https://openstarlab.readthedocs.io/en/latest/Pre_Processing/Sports/Phase_data/index.html).

![image](phase/sports/soccer/assets/phases_of_play_diagram.png)

---

## Installation
- Install [pytorch](https://pytorch.org/get-started/locally/) (recommended version 2.4.0 linux pip python3.9 cuda11.8)
```
pip install torch torchvision torchaudio
```
- To install this package via PyPI
```
pip install openstarlab-phaselearn
```
- To install manually
```
git clone git@github.com:open-starlab/PhaseLearn.git
cd ./PhaseLearn
pip install -e .
```

## Quick Start
Get started with inference using pre-trained models.

1. **Download Pre-trained Model**: Download the model weights from [MODEL URL](https://tsukuba.repo.nii.ac.jp/records/2021338) and place them in the ```model/``` directory.

1. **Generate Phase Data**: Before estimating, you must convert the raw tracking into the ```Phase Data``` format.
    - [PreProcessing Documentation](https://openstarlab.readthedocs.io/en/latest/Pre_Processing/Sports/Phase_data/index.html)

1. **Run Inference**: Perform phase estimation on your data.
    - [Inference Example Guide](https://openstarlab.readthedocs.io/en/latest/PhaseLearn_Modeling/Sports/Soccer/example.html)

## Training and Analysis from Scratch

Follow these steps to train your own play phase model using the SoccerTrack-v2 dataset.

1. **Data Acquisition**:
    - **Tracking Data**: Obtain the raw data from [SoccerTrack-v2](https://atomscott.github.io/SoccerTrack-v2/).
      - [Required Files Guide](https://openstarlab.readthedocs.io/en/latest/PhaseLearn_Modeling/Sports/Soccer/models_framework.html) (Note: Different files are required for Match IDs >= 130000 and < 130000).
    - **Phase Annotation Data**: Download the play phase annotation data from [DATA URL](https://tsukuba.repo.nii.ac.jp/records/2021338) and place them in the ```data/``` directory.

2. **Generate Phase Data**: Before training, you must convert the raw tracking into the ```Phase Data``` format.
    - [PreProcessing Documentation](https://openstarlab.readthedocs.io/en/latest/Pre_Processing/Sports/Phase_data/index.html)

3. **Training & Evaluation**: Once the data is prepared, you can execute the training pipeline.
    - [Train, Inference and Evaluation Example Guide](https://openstarlab.readthedocs.io/en/latest/PhaseLearn_Modeling/Sports/Soccer/example.html)

## Repository Layout
```
PhaseLearn/
├── phase/sports/soccer/         
│   ├── dataloaders/data_module.py
│   ├── inference/inference.py
│   ├── main_class_soccer/main.py
│   ├── models/
│   │   ├── model_yaml/
│   │   │   ├── train_baller2vec.yaml
│   │   │   ├── train_gat_transformer.yaml
│   │   │   ├── train_gcn_transformer.yaml
│   │   │   └── train_transformer.yaml
│   │   ├── baller2vec.py
│   │   ├── gat_transformer.py
│   │   ├── gcn_transformer.py
│   │   └── transformer.py
│   ├── trainers/train.py
│   └── utils/
│       ├── evaluation.py
│       ├── load_train_data.py
│       └── preprocessing.py
├── data/                              # Data storage (gitignored except .gitkeep)
│   ├── phase_annotation_data/
│   │   ├── 117092/
│   │   │   ├── 117092_00_01-04_18_annotation
│   │   │   ├── ...
│   │   ├── ...
│   ├── phase_data/
│   │   ├── bepro/
│   │   │   ├── 117092/117092_main_data
│   │   │   ├── ...
│   │   └── statsbomb_skillcorner/
│   │       ├── 3894537_1018887/3894537_1018887_main_data
│   │       ├── ...
│   └── train_data/bepro/              # generated by preprocessing_data()
│       ├── label_np.bpy
│       └── sequence_np.bpy
└── model/                              # Model storage (gitignored except .gitkeep)
    ├── baller2vec/
    │   ├── ...
    ├── gat_transformer/
    │   ├── 2team_mode/
    │   │   ├── 20251221_155257/run1
    │   │   │   ├── best.pth
    │   │   │   ├── hyperparameters.json
    │   │   │   ├── loss.csv
    │   │   │   └── model_stats.txt
    │   │   ├── ...
    │   ├── ...
    ├── gcn_transformer/
    │   ├── ...
    └── trnsformer/
        ├── ...
```

## RoadMap
- [x] Release the package
- [x] Provide pre-trained models
- [x] Provide phase dataset

## Other Information
Development torch version
```
version 0.0.2 linux pip python3.9 cuda11.8 
```

## Citation

If you use phaselearn modeling in your research, please cite it as follows:

```bibtex
@article{playphase,
  title={Estimating Probability Distributions of FIFA-Defined Phases of Play Based on Inter-Analyst Diversity},
  author={Kento Kuroda, Keisuke Fujii and Yoshinari Kameda},
  journal={International Journal of Computer Science in Sport},
  year={2026},
  volume={XX},
  pages={XXX-XXX},
  publisher={Publisher}
}
```

## Developer
<table>
  <tbody>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/KentoKuroda"><img src="https://github.com/KentoKuroda.png" width="100px;" alt="Kento Kuroda"/><br /><sub><b>Kento Kuroda</b></sub></a><br /><a href="#Developer-KentoKuroda" title="Lead Developer">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/kenjiro-mk"><img src="https://github.com/kenjiro-mk.png" width="100px;" alt="Kenjiro Ide"/><br /><sub><b>Kenjiro Ide</b></sub></a><br /><a href="#Developer-KenjiroIde" title="Developer">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/keisuke198619"><img src="https://github.com/keisuke198619.png" width="100px;" alt="Keisuke Fujii"/><br /><sub><b>Keisuke Fujii</b></sub></a><br /><a href="#lead-KeisukeFujii" title="Team Leader">🧑‍💻</a></td>
    </tr>
  </tbody>
</table>