examples/0_quick_start_guide.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 🌀 Quick Start Guide: It's all starting to unravel!\n",
    "\n",
    "In this example we'll run through all the basic features the `unravelsports` package offers for converting a `kloppy` dataset of soccer tracking data into graphs for training binary classification graph neural networks using the `spektral` library.\n",
    "\n",
    "This guide will go through the following steps:\n",
    "\n",
    "- [**1. Process Data**](#1-processing-data). We'll show how to load a `kloppy` dataset and convert each individual frame into a single graph. All necessary steps (like setting the correct coordinate system, and left-right normalization) are done under the hood of the converter.\n",
    "- [**1.1 Split Data**](#11-split-data).\n",
    "- [**2. Compile Model**](#2-compile-model). We compile the built-in binary classification model as presented in [A Graph Neural Network Deep-dive into Successful Counterattacks {A. Sahasrabudhe & J. Bekkers}](https://github.com/USSoccerFederation/ussf_ssac_23_soccer_gnn).\n",
    "- [**3. Fit Model**](#3-fit-model). Using the compiled model we fit it on the training set created in step [1.1 Splitting Data](#11-split-data).\n",
    "- [**4. Evaluate Model Performance**](#4-evaluate-model-performance). We calculated model performance using the `metrics` passed into the compiled model.\n",
    "- [**5. Predict**](#5-predict). Finally, we apply the trained model to unseen data.\n",
    "\n",
    "<br>\n",
    "<i>Before we get started it is important to note that the <b>unravelsports</b> library does not have built in functionality to create binary labels, these will need to be supplied by the reader. In this example we use the <b>dummy_labels()</b> functionality that comes with the package. This function creates a single binary label for each frame by randomly assigning it a 0 or 1 value.\n",
    "\n",
    "When supplying your own labels they need to be in the form of a dictionary (more information on this can be found in the [in-depth Walkthrough](1_kloppy_gnn_train.ipynb)) </i>\n",
    "\n",
    "\n",
    "\n",
    "-----\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first thing is to run `pip install unravelsports` if you haven't already!\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install unravelsports --quiet"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. Process Data\n",
    "\n",
    "1. Load [Kloppy](https://github.com/PySport/kloppy) dataset. \n",
    "    See [in-depth Tutorial](1_kloppy_gnn_train.ipynb) on how do processes multiple match files, and to see an overview of all possible settings.\n",
    "2. Convert to Graph format using `SoccerGraphConverter`\n",
    "3. Create dataset for easy processing with [Spektral](https://graphneural.network/) using `CustomSpektralDataset`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from unravel.soccer import SoccerGraphConverter\n",
    "from unravel.utils import CustomSpektralDataset\n",
    "\n",
    "from kloppy import skillcorner\n",
    "\n",
    "from unravel.utils import dummy_labels\n",
    "\n",
    "# Load Kloppy dataset\n",
    "kloppy_dataset = skillcorner.load_open_data(\n",
    "    match_id=4039,\n",
    "    include_empty_frames=False,\n",
    "    limit=500,  # limit to 500 frames in this example\n",
    ")\n",
    "\n",
    "# Initialize the Graph Converter, with dataset and labels\n",
    "# Here we use the default settings\n",
    "converter = SoccerGraphConverter(\n",
    "    dataset=kloppy_dataset, labels=dummy_labels(kloppy_dataset)\n",
    ")\n",
    "\n",
    "# Compute the graphs and add them to the CustomSpektralDataset\n",
    "dataset = CustomSpektralDataset(graphs=converter.to_spektral_graphs())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1.1 Split Data\n",
    "\n",
    "Split the dataset with the built in `split_test_train_validation` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from spektral.data import DisjointLoader\n",
    "\n",
    "train, test, val = dataset.split_test_train_validation(\n",
    "    split_train=4, split_test=1, split_validation=1, random_seed=42\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Compile Model\n",
    "\n",
    "1. Initialize the `CrystalGraphClassifier`.\n",
    "2. Compile the model with a loss function, optimizer and your preferred metrics.\n",
    "\n",
    "Note: The model settings are chosen to reflect the model used in [A Graph Neural Network Deep-dive into Successful Counterattacks {A. Sahasrabudhe & J. Bekkers}](https://github.com/USSoccerFederation/ussf_ssac_23_soccer_gnn)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from unravel.classifiers import CrystalGraphClassifier\n",
    "\n",
    "from tensorflow.keras.losses import BinaryCrossentropy\n",
    "from tensorflow.keras.optimizers import Adam\n",
    "from tensorflow.keras.metrics import AUC, BinaryAccuracy\n",
    "\n",
    "model = CrystalGraphClassifier()\n",
    "\n",
    "model.compile(\n",
    "    loss=BinaryCrossentropy(), optimizer=Adam(), metrics=[AUC(), BinaryAccuracy()]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3. Fit Model\n",
    "\n",
    "1. Create a [`DisjointLoader`](https://graphneural.network/loaders/#disjointloader) for training and validation sets.\n",
    "2. Fit the model. Note: set `use_multiprocessing=True` to speed up training significantly. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from tensorflow.keras.callbacks import EarlyStopping\n",
    "\n",
    "batch_size = 32\n",
    "epochs = 10\n",
    "\n",
    "loader_tr = DisjointLoader(train, batch_size=batch_size)\n",
    "loader_va = DisjointLoader(val, epochs=1, shuffle=False, batch_size=batch_size)\n",
    "\n",
    "model.fit(\n",
    "    loader_tr.load(),\n",
    "    epochs=epochs,\n",
    "    steps_per_epoch=loader_tr.steps_per_epoch,\n",
    "    use_multiprocessing=True,\n",
    "    validation_data=loader_va.load(),\n",
    "    callbacks=[EarlyStopping(monitor=\"loss\", patience=5, restore_best_weights=True)],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4. Evaluate Model Performance\n",
    "\n",
    "1. Create another `DisjointLoader`, this time for the test set.\n",
    "2. Evaluate model performance on the test set. This evaluation function uses the `metrics` passed to `model.compile`\n",
    "\n",
    "Note: Our performance is really bad because we're using random labels, very few epochs and a small dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "loader_te = DisjointLoader(test, epochs=1, shuffle=False, batch_size=batch_size)\n",
    "results = model.evaluate(loader_te.load())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5. Predict\n",
    "\n",
    "1. Use unseen data to predict on. In this example we're using the test dataset.\n",
    "2. We have to re-create `loader_te` because `DisjointLoader` is a generator.\n",
    "3. Setting `batch_size` and `use_multiprocessing=True` on prediction helps speed up the prediction"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "loader_te = DisjointLoader(test, batch_size=batch_size, epochs=1, shuffle=False)\n",
    "loaded_pred = model.predict(loader_te.load(), use_multiprocessing=True)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}