Add Intrusion and Avoidance section to user guide

Demonstrates compute_intrusion and compute_avoidance using the
existing bottleneck demo data. Shows per-agent results and temporal
evolution plots of the frame-averaged dimensionless numbers.

Author: chraibi

notebooks/user_guide.ipynb

@@ -3352,6 +3352,100 @@
     ":::"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Dimensionless Numbers: Intrusion and Avoidance\n",
+    "\n",
+    "The dimensionless Intrusion number $\\mathcal{I}n$ and Avoidance number $\\mathcal{A}v$\n",
+    "classify crowd flow regimes based on personal space intrusions and collision anticipation\n",
+    "([Cordes et al., *PNAS Nexus*, 2024](https://doi.org/10.1093/pnasnexus/pgae120)).\n",
+    "\n",
+    "The **Intrusion number** quantifies encroachment on personal space:\n",
+    "\n",
+    "$$\n",
+    "\\mathcal{I}n_i = \\sum_{j \\in \\mathcal{N}_i}\n",
+    "\\left(\\frac{r_{\\text{soc}} - \\ell_{\\text{min}}}{r_{ij} - \\ell_{\\text{min}}}\\right)^2\n",
+    "$$\n",
+    "\n",
+    "The **Avoidance number** quantifies the imminence of collisions via the time-to-collision (TTC):\n",
+    "\n",
+    "$$\n",
+    "\\mathcal{A}v_i = \\max_{j \\in \\mathcal{N}'_i}\n",
+    "\\frac{\\tau_0}{\\tau_{ij}}\n",
+    "$$\n",
+    "\n",
+    "where $r_{\\text{soc}} = 0.8\\,$m is the social radius, $\\ell_{\\text{min}} = 0.2\\,$m the pedestrian diameter,\n",
+    "and $\\tau_0 = 3\\,$s a reference timescale."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "from pedpy import compute_intrusion, compute_avoidance, IntrusionMethod\n",
+    "\n",
+    "intrusion = compute_intrusion(traj_data=traj)\n",
+    "intrusion.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "avoidance = compute_avoidance(\n",
+    "    traj_data=traj, frame_step=5, tau_0=3.0, radius=0.2\n",
+    ")\n",
+    "avoidance.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Temporal evolution\n",
+    "\n",
+    "We can visualize how these numbers evolve over time by averaging over all pedestrians per frame:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "mean_in = intrusion.groupby(\"frame\")[\"intrusion\"].mean()\n",
+    "mean_av = avoidance.groupby(\"frame\")[\"avoidance\"].mean()\n",
+    "\n",
+    "fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))\n",
+    "\n",
+    "ax1.plot(mean_in.index / traj.frame_rate, mean_in.values)\n",
+    "ax1.set_xlabel(\"Time / s\")\n",
+    "ax1.set_ylabel(r\"$\\langle \\mathcal{I}n \\rangle$\")\n",
+    "ax1.set_title(\"Mean Intrusion Number\")\n",
+    "\n",
+    "ax2.plot(mean_av.index / traj.frame_rate, mean_av.values)\n",
+    "ax2.set_xlabel(\"Time / s\")\n",
+    "ax2.set_ylabel(r\"$\\langle \\mathcal{A}v \\rangle$\")\n",
+    "ax2.set_title(\"Mean Avoidance Number\")\n",
+    "\n",
+    "fig.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -5207,4 +5301,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}