Add Tutorial.ipynb

.github/workflows/test.yml

@@ -51,6 +51,10 @@ jobs:
       run: mypy .
     - name: Run tests (Python)
       run: pytest
+    - name: Lint Jupyter with Ruff
+      run: nbqa ruff *.ipynb
+    - name: Lint Jupyter with Mypy
+      run: nbqa mypy *.ipynb
     - name: Build with Maturin
       run: maturin build --release --out=dist/
     - name: Check with Twine

Tutorial.ipynb

@@ -0,0 +1,163 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6b536cab-71b4-43dd-8312-ee913a4d96d1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import evalica\n",
+    "import numpy as np\n",
+    "import numpy.typing as npt\n",
+    "import pandas as pd\n",
+    "import plotly.express as px\n",
+    "from evalica import Winner\n",
+    "from plotly.graph_objects import Figure"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cfed1bc3-7b95-4af6-b234-f94240706e24",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "evalica.__version__"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e647667c-adb8-4f16-9b7c-993cf2739c2b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df_food = pd.read_csv(\"food.csv\", dtype=str)\n",
+    "df_food.head(5)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "024e6a61-0ddb-4235-aa7b-6fb5280b5d9e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "index: dict[str, int] = {}\n",
+    "\n",
+    "for xy in zip(df_food[\"left\"], df_food[\"right\"], strict=False):\n",
+    "    for e in xy:\n",
+    "        index[e] = index.get(e, len(index))\n",
+    "\n",
+    "xs = [index[x] for x in df_food[\"left\"]]\n",
+    "ys = [index[y] for y in df_food[\"right\"]]\n",
+    "ws = df_food[\"winner\"].map({\n",
+    "        \"left\": Winner.X,\n",
+    "        \"right\": Winner.Y,\n",
+    "        \"tie\": Winner.Draw,\n",
+    "    }).tolist()\n",
+    "\n",
+    "wins, ties = evalica.matrices(xs, ys, ws)\n",
+    "\n",
+    "wins, ties"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8df08cae-1aea-41e6-a6b3-a6a856d5050c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "scores, _iterations = evalica.bradley_terry(wins + ties / 2, tolerance=1e-4, limit=100)\n",
+    "scores"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1d331724-d4aa-4270-b0d7-d07ecab17ac7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "scores, _v, _iterations = evalica.newman(wins.astype(np.float64), ties / 2, .5, tolerance=1e-4, limit=100)\n",
+    "scores"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "62c6a626-0d64-4b8a-979b-5bf33dac67ba",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def to_pairwise(scores: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:\n",
+    "    return scores[:, np.newaxis] / (scores + scores[:, np.newaxis])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d1bff4e2-441d-48ad-93e4-e075b0ecb007",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "to_pairwise(scores)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7e7dba72-29d8-4835-b290-2fbccd0d59de",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def visualize(df_pairwise: npt.NDArray[np.float64]) -> Figure:\n",
+    "    fig = px.imshow(df_pairwise, color_continuous_scale=\"RdBu\", text_auto=\".2f\")\n",
+    "    fig.update_layout(xaxis_title=\"Loser\", yaxis_title=\"Winner\", xaxis_side=\"top\")\n",
+    "    fig.update_traces(hovertemplate=\"Winner: %{y}<br>Loser: %{x}<br>Fraction of Wins: %{z}<extra></extra>\")\n",
+    "    return fig"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5241affc-7b81-49f1-9dd0-f2b7f03d2337",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "visualize(to_pairwise(scores))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c92c5a08-3263-4dd4-b8a4-916809a3b0fd",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.11.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pyproject.toml

@@ -22,7 +22,7 @@ classifiers = [
 dynamic = ["version"]
 
 [project.optional-dependencies]
-dev = ["hypothesis[numpy]", "mypy", "pandas", "pytest", "ruff", "twine"]
+dev = ["hypothesis[numpy]", "mypy", "nbqa", "notebook", "pandas", "pytest", "ruff", "twine"]
 
 [tool.maturin]
 python-source = "python"
@@ -32,6 +32,9 @@ ignore_missing_imports = true
 plugins = ["numpy.typing.mypy_plugin"]
 strict = true
 
+[tool.nbqa.addopts]
+ruff = ["--ignore=B018"]
+
 [tool.ruff]
 line-length = 120
 target-version = "py312"