text updates

.gitignore

@@ -182,4 +182,6 @@ build.py
 **/pickle_files
 
 /models
-/dev
+/dev
+
+*.ipynb

README.md

@@ -54,6 +54,7 @@ Due to compatibility issues **unravelsports** currently only works on Python 3.1
 spektral==1.20.0 
 tensorflow==2.14.0 
 keras==2.14.0
+kloppy==3.15.0
 ```
 These dependencies come pre-installed with the package. It is advised to create a [virtual environment](https://virtualenv.pypa.io/en/latest/).
 
@@ -67,21 +68,19 @@ An overview on how to contribute can be found in the [**contributing guide**](CO
 
 🌀 Citation
 ----
-If you use this repository for any educational purposes, research, project etc., please reference either/or:
+If you use this repository for any educational purposes, research, project etc., please reference both:
 
-📎 [Bekkers, J., & Dabadghao, S. (2019). Flow motifs in soccer: What can passing behavior tell us?. Journal of Sports Analytics, 5(4), 299-311.](https://content.iospress.com/download/journal-of-sports-analytics/jsa190290?id=journal-of-sports-analytics%2Fjsa190290)
+📎 [The `unravelsports` package](https://github.com/unravelsports/unravelsports).
 <details>
 <summary>BibTex</summary>
 <pre>
-@article{bekkers2019flow,
-  title={Flow motifs in soccer: What can passing behavior tell us?},
-  author={Bekkers, Joris and Dabadghao, Shaunak},
-  journal={Journal of Sports Analytics},
-  volume={5},
-  number={4},
-  pages={299--311},
-  year={2019},
-  publisher={IOS Press}
+@software{unravelsports2024repository,
+  author = {Bekkers, Joris},
+  title = {unravelsports},
+  version = {0.1.0},
+  year = {2024},
+  publisher = {GitHub},
+  url = {https://github.com/unravelsports/unravelsports}
 }
 </pre>
 </details>

examples/0_quick_start_guide.ipynb

@@ -6,12 +6,34 @@
    "source": [
     "## 🌀 Quick Start Guide: It's all starting to unravel!\n",
     "\n",
-    "First run `pip install unravelsports` if you haven't already!\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,
@@ -25,9 +47,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 1. Processing Data\n",
+    "### 1. Process Data\n",
     "\n",
-    "1. Load [Kloppy](https://github.com/PySport/kloppy) dataset. See [in-depth Tutorial](1_kloppy_gnn_train.ipynb) on how do processes multiple match files.\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 `GraphConverter`\n",
     "3. Create dataset for easy processing with [Spektral](https://graphneural.network/) using `CustomSpektralDataset`"
    ]
@@ -52,7 +75,8 @@
     "    limit=500,  # limit to 500 frames in this example\n",
     ")\n",
     "\n",
-    "# Initialize the Graph Converter, with dataset, labels and settings\n",
+    "# Initialize the Graph Converter, with dataset and labels\n",
+    "# Here we use the default settings\n",
     "converter = GraphConverter(dataset=kloppy_dataset, labels=dummy_labels(kloppy_dataset))\n",
     "\n",
     "# Compute the graphs and add them to the CustomSpektralDataset\n",
@@ -63,7 +87,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 2. Split Data\n",
+    "#### 1.1 Split Data\n",
     "\n",
     "Split the dataset with the built in `split_test_train_validation` method."
    ]
@@ -85,10 +109,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### 2. Compile Model\n",
+    "### 2. Compile Model\n",
     "\n",
     "1. Initialize the `CrystalGraphClassifier`.\n",
-    "2. Compile the model with a loss function, optimizer and your preferred metrics."
+    "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)"
    ]
   },
   {