Add Gauss speed profile

notebooks/user_guide.ipynb

@@ -2363,32 +2363,49 @@
    "source": [
     "#### Speed Profiles\n",
     "\n",
-    "Currently, it is possible to compute either the Voronoi or arithmetic speed profiles.\n",
+    "This documentation describes the methods available for computing speed profiles within a specified area, focusing on pedestrian movements. Four distinct methods are detailed: Voronoi, Arithmetic, Mean, and Gauss speed profiles.\n",
     "\n",
     "**Voronoi speed profile**\n",
     "\n",
-    "The Voronoi speed is computed as a weighted mean of the pedestrian's speed, whose Voronoi cell ($V_i$) intersects with the grid cell ($M$). The weighted is given by the proportion of the Voronoi, which lies inside the gird cell.\n",
-    "\n",
+    "The Voronoi speed profile $v_{\\text{voronoi}}$ is computed from a weighted mean of pedestrian speeds.\n",
+    " It utilizes the area overlap between a pedestrian's Voronoi cell ($V_i$) and the grid cell ($c$). The weight corresponds to the fraction of the Voronoi cell residing within the grid cell, thereby integrating speed across this intersection:\n",
+    " \n",
     "$$\n",
-    "        v_{voronoi}(t) = { \\int\\int v_{xy} dxdy \\over A(M)},\n",
+    "        v_{\\text{voronoi}} = { \\int\\int v_{xy} dxdy \\over A(c)},\n",
     "$$\n",
     "\n",
+    "where $A(c)$ represents the area of the grid cell $c$.\n",
     "\n",
     "**Arithmetic Voronoi speed profile**\n",
     "\n",
-    "The arithmetic Voronoi speed $v_{arithmetic}$ is computed as the mean of each pedestrian's speed ($v_i$), whose Voronoi cell $V_i$ intersects with grid cell $M$:\n",
+    "The arithmetic Voronoi speed $v_{\\text{arithmetic}}$ is computed as the mean of each pedestrian's speed ($v_i$), whose Voronoi cell $V_i$ intersects with grid cell $c$:\n",
     "\n",
     "$$\n",
-    "        v_{arithmetic} = \\frac{1}{N} \\sum_{i \\in V_i \\cap P_M} v_i,\n",
+    "        v_{\\text{arithmetic}} = \\frac{1}{N} \\sum_{i \\in V_i \\cap P_c} v_i,\n",
     "$$\n",
     "\n",
+    "with $N$ being the total number of pedestrians whose Voronoi cells overlap with grid cell $c$.\n",
+    "\n",
     "**Mean speed profile**\n",
     "\n",
-    "The mean speed profile is computed by the mean speed of all pedestrians $P_M$ inside the grid cell $M$:\n",
+    "The mean speed profile is computed by the average speed of all pedestrians $P_c$ present within a grid cell $c$:\n",
     "\n",
     "$$\n",
-    "        v_{mean} = \\frac{1}{N} \\sum_{i \\in P_M} v_i\n",
-    "$$"
+    "        v_{\\text{mean}} = \\frac{1}{N} \\sum_{i \\in P_c} v_i\n",
+    "$$\n",
+    "\n",
+    "where $N$ denotes the number of pedestrians in grid cell $c$.\n",
+    "\n",
+    "**Gauss speed profiles**\n",
+    "\n",
+    "Calculates a speed profile based on Gaussian weights for an array of pedestrian locations and velocities. The speed, weighted at a grid cell $c$ considering its distance $\\delta = \\boldsymbol{r}_i - \\boldsymbol{c}$ from an agent, is determined as follows:\n",
+    "    \n",
+    "$$     \n",
+    "        v_{\\text{gauss}} = \\frac{\\sum_{i=1}^{N}{\\big(w_i\\cdot v_i\\big)}}{\\sum_{i=1}^{N} w_i},\n",
+    "$$\n",
+    "with \n",
+    "$w_i = \\frac{1} {\\sigma \\cdot \\sqrt{2\\pi}} \\exp\\big(-\\frac{\\delta^2}{2\\sigma^2}\\big)\\; \\text{and}\\; \\sigma = \\frac{FWHM}{2\\sqrt{2\\ln(2)}}.\n",
+    "$"
    ]
   },
   {
@@ -2420,6 +2437,14 @@
     "    walkable_area=walkable_area,\n",
     "    grid_size=grid_size,\n",
     "    speed_method=SpeedMethod.MEAN,\n",
+    ")\n",
+    "\n",
+    "gauss_speed_profile = compute_speed_profile(\n",
+    "    data=profile_data,\n",
+    "    walkable_area=walkable_area,\n",
+    "    grid_size=grid_size,\n",
+    "    gaussian_width=0.5,\n",
+    "    speed_method=SpeedMethod.GAUSSIAN,\n",
     ")"
    ]
   },
@@ -2436,8 +2461,7 @@
     "from pedpy import plot_profiles\n",
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "fig, (ax0, ax1, ax2) = plt.subplots(nrows=1, ncols=3, layout=\"constrained\")\n",
-    "fig.set_size_inches(10, 5)\n",
+    "fig, ((ax0, ax1), (ax2, ax3)) = plt.subplots(nrows=2, ncols=2)\n",
     "fig.suptitle(\"Speed profile\")\n",
     "cm = plot_profiles(\n",
     "    walkable_area=walkable_area,\n",
@@ -2459,14 +2483,25 @@
     ")\n",
     "cm = plot_profiles(\n",
     "    walkable_area=walkable_area,\n",
-    "    profiles=mean_speed_profile,\n",
+    "    profiles=gauss_speed_profile,\n",
     "    axes=ax2,\n",
     "    label=\"v / m/s\",\n",
     "    vmin=0,\n",
     "    vmax=1.5,\n",
+    "    title=\"Gauss\",\n",
+    ")\n",
+    "cm = plot_profiles(\n",
+    "    walkable_area=walkable_area,\n",
+    "    profiles=mean_speed_profile,\n",
+    "    axes=ax3,\n",
+    "    label=\"v / m/s\",\n",
+    "    vmin=0,\n",
+    "    vmax=1.5,\n",
     "    title=\"Mean\",\n",
     ")\n",
-    "\n",
+    "plt.subplots_adjust(\n",
+    "    left=None, bottom=None, right=None, top=None, wspace=0, hspace=0.6\n",
+    ")\n",
     "plt.show()"
    ]
   },
@@ -3305,7 +3340,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.8"
+   "version": "3.12.2"
   }
  },
  "nbformat": 4,

pedpy/data/geometry.py

@@ -334,10 +334,12 @@ def _polygon_from_wkt(wkt_input: str) -> shapely.Polygon:
 
 
 def _polygon_from_shapely(
-    geometry_input: shapely.Polygon
-    | shapely.MultiPolygon
-    | shapely.GeometryCollection
-    | shapely.MultiPoint,
+    geometry_input: (
+        shapely.Polygon
+        | shapely.MultiPolygon
+        | shapely.GeometryCollection
+        | shapely.MultiPoint
+    ),
 ) -> shapely.Polygon:
     def _polygons_from_multi_polygon(
         multi_polygon: shapely.MultiPolygon,

pedpy/internal/utils.py

@@ -1,4 +1,5 @@
 """Module containing internal utilities"""
+
 import functools
 
 

pedpy/io/trajectory_loader.py

@@ -1,4 +1,5 @@
 """Load trajectories to the internal trajectory data format."""
+
 import math
 import pathlib
 import sqlite3

pedpy/methods/density_calculator.py

@@ -1,4 +1,5 @@
 """Module containing functions to compute densities."""
+
 from typing import Tuple
 
 import numpy as np

pedpy/methods/flow_calculator.py

@@ -1,4 +1,5 @@
 """Module containing functions to compute flows."""
+
 from typing import Tuple
 
 import pandas as pd

pedpy/methods/method_utils.py

@@ -1,4 +1,5 @@
 """Helper functions for the analysis methods."""
+
 import itertools
 import logging
 from collections import defaultdict