From 279d886c9c380a3bf17439c08cb30cf84ad8aa51 Mon Sep 17 00:00:00 2001
From: "Daniel G. Krakowczyk" <daniel.krakowczyk@uni-potsdam.de>
Date: Wed, 6 Sep 2023 11:43:10 +0200
Subject: [PATCH] docs: Add latex formulas to event property docstrings (#491)

Co-authored-by: Jakob Chwastek <chwastek@uni-potsdam.de>
---
 src/pymovements/events/properties.py | 51 ++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)

diff --git a/src/pymovements/events/properties.py b/src/pymovements/events/properties.py
index 2310acdb9..297d64f9f 100644
--- a/src/pymovements/events/properties.py
+++ b/src/pymovements/events/properties.py
@@ -24,7 +24,6 @@
 
 import polars as pl
 
-
 EVENT_PROPERTIES: dict[str, Callable] = {}
 
 
@@ -42,6 +41,16 @@ def amplitude(
 ) -> pl.Expr:
     """Amplitude of an event.
 
+    The amplitude is calculated as:
+
+    .. math::
+        \\text{Amplitude} = \\sqrt{(x_{\\text{max}} - x_{\\text{min}})^2 +
+        (y_{\\text{max}} - y_{\\text{min}})^2}
+
+    where :math:`(x_{\\text{min}},\\; x_{\\text{max}})` and
+    :math:`(y_{\\text{min}},\\; y_{\\text{max}})` are the minimum and maximum values of the
+    :math:`x` and :math:`y` components of the gaze positions during an event.
+
     Parameters
     ----------
     position_column
@@ -71,7 +80,17 @@ def dispersion(
         position_column: str = 'position',
         n_components: int = 2,
 ) -> pl.Expr:
-    """Dispersion of an event.
+    """
+    Dispersion of an event.
+
+    The dispersion is calculated as:
+
+    .. math::
+        \\text{Dispersion} = x_{\\text{max}} - x_{\\text{min}} + y_{\\text{max}} - y_{\\text{min}}
+
+    where :math:`(x_{\\text{min}},\\; x_{\\text{max}})` and
+    :math:`(y_{\\text{min}},\\; y_{\\text{max}})` are the minimum and maximum values of the
+    :math:`x` and :math:`y` components of the gaze positions during an event.
 
     Parameters
     ----------
@@ -101,6 +120,14 @@ def disposition(
 ) -> pl.Expr:
     """Disposition of an event.
 
+    The disposition is calculated as:
+
+    .. math::
+        \\text{Disposition} = \\sqrt{(x_0 - x_n)^2 + (y_0 - y_n)^2}
+
+    where :math:`x_0` and :math:`y_0` are the coordinates of the starting position and
+    :math:`x_n` and :math:`y_n` are the coordinates of the ending position of an event.
+
     Parameters
     ----------
     position_column
@@ -143,6 +170,18 @@ def location(
 ) -> pl.Expr:
     """Location of an event.
 
+    For method ``mean`` the location is calculated as:
+
+    .. math::
+        \\text{Location} = \\frac{1}{n} \\sum_{i=1}^n \\text{position}_i
+
+    For method ``median`` the location is calculated as:
+
+    .. math::
+        \\text{Location} = \\text{median} \\left(\\text{position}_1, \\ldots,
+         \\text{position}_n \\right)
+
+
     Parameters
     ----------
     method
@@ -192,6 +231,14 @@ def peak_velocity(
 ) -> pl.Expr:
     """Peak velocity of an event.
 
+    The peak velocity is calculated as:
+
+    .. math::
+        \\text{Peak Velocity} = \\max \\left(\\sqrt{v_x^2 + v_y^2} \\right)
+
+    where :math:`v_x` and :math:`v_y` are the velocity components in :math:`x` and :math:`y`
+    direction, respectively.
+
     Parameters
     ----------
     velocity_column