Repository: aeye-lab/pymovements
Pull request #423 (2023-05-26 09:49:40)

refactor(events)!: Rename position property to location
This way gaze position and event location is clearly separated and no confusion will occur

codecov[bot]: ## [Codecov](https://app.codecov.io/gh/aeye-lab/pymovements/pull/423?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab) Report
Patch coverage: **`100.00`**% and no project coverage change.
> Comparison is base [(`d9a94ef`)](https://app.codecov.io/gh/aeye-lab/pymovements/commit/d9a94ef798b53f4c0f1bff5fa3010cad85da4f51?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab) 100.00% compared to head [(`33676c1`)](https://app.codecov.io/gh/aeye-lab/pymovements/pull/423?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab) 100.00%.

<details><summary>Additional details and impacted files</summary>


```diff
@@            Coverage Diff            @@
##              main      #423   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           55        55           
  Lines         1908      1908           
  Branches       425       425           
=========================================
  Hits          1908      1908           
```


| [Impacted Files](https://app.codecov.io/gh/aeye-lab/pymovements/pull/423?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab) | Coverage Δ | |
|---|---|---|
| [src/pymovements/events/\_\_init\_\_.py](https://app.codecov.io/gh/aeye-lab/pymovements/pull/423?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab#diff-c3JjL3B5bW92ZW1lbnRzL2V2ZW50cy9fX2luaXRfXy5weQ==) | `100.00% <ø> (ø)` | |
| [src/pymovements/events/event\_properties.py](https://app.codecov.io/gh/aeye-lab/pymovements/pull/423?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab#diff-c3JjL3B5bW92ZW1lbnRzL2V2ZW50cy9ldmVudF9wcm9wZXJ0aWVzLnB5) | `100.00% <100.00%> (ø)` | |


</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/aeye-lab/pymovements/pull/423?src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab).   
:loudspeaker: Do you have feedback about the report comment? [Let us know in this issue](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab).


Patch:
diff --git a/src/pymovements/events/__init__.py b/src/pymovements/events/__init__.py
index 9151a9d..2bae2be 100644
--- a/src/pymovements/events/__init__.py
+++ b/src/pymovements/events/__init__.py
@@ -58,7 +58,7 @@
     pymovements.events.event_properties.dispersion
     pymovements.events.event_properties.disposition
     pymovements.events.event_properties.peak_velocity
-    pymovements.events.event_properties.position
+    pymovements.events.event_properties.location
 """
 from pymovements.events.detection.idt import idt
 from pymovements.events.detection.ivt import ivt
diff --git a/src/pymovements/events/event_properties.py b/src/pymovements/events/event_properties.py
index 19212f6..b61fd82 100644
--- a/src/pymovements/events/event_properties.py
+++ b/src/pymovements/events/event_properties.py
@@ -135,41 +135,13 @@ def duration() -> pl.Expr:
 
 
 @register_event_property
-def peak_velocity(
-        *,
-        velocity_column: str = 'velocity',
-        n_components: int = 2,
-) -> pl.Expr:
-    """Peak velocity of an event.
-
-    Parameters
-    ----------
-    velocity_column
-        The column name of the velocity tuples.
-    n_components:
-        Number of positional components. Usually these are the two components yaw and pitch.
-
-    Raises
-    ------
-    ValueError
-        If number of components is not 2.
-    """
-    _check_has_two_componenents(n_components)
-
-    x_velocity = pl.col(velocity_column).arr.get(0)
-    y_velocity = pl.col(velocity_column).arr.get(1)
-
-    return (x_velocity.pow(2) + y_velocity.pow(2)).sqrt().max()
-
-
-@register_event_property
-def position(
+def location(
         method: str = 'mean',
         *,
         position_column: str = 'position',
         n_components: int = 2,
 ) -> pl.Expr:
-    """Centroid position of an event.
+    """Location of an event.
 
     Parameters
     ----------
@@ -212,6 +184,34 @@ def position(
     return pl.concat_list(component_expressions).first()
 
 
+@register_event_property
+def peak_velocity(
+        *,
+        velocity_column: str = 'velocity',
+        n_components: int = 2,
+) -> pl.Expr:
+    """Peak velocity of an event.
+
+    Parameters
+    ----------
+    velocity_column
+        The column name of the velocity tuples.
+    n_components:
+        Number of positional components. Usually these are the two components yaw and pitch.
+
+    Raises
+    ------
+    ValueError
+        If number of components is not 2.
+    """
+    _check_has_two_componenents(n_components)
+
+    x_velocity = pl.col(velocity_column).arr.get(0)
+    y_velocity = pl.col(velocity_column).arr.get(1)
+
+    return (x_velocity.pow(2) + y_velocity.pow(2)).sqrt().max()
+
+
 def _check_has_two_componenents(n_components: int) -> None:
     """Check that number of componenents is two."""
     if n_components != 2:


Test patch:
diff --git a/tests/dataset/dataset_test.py b/tests/dataset/dataset_test.py
index f40899b..41880e5 100644
--- a/tests/dataset/dataset_test.py
+++ b/tests/dataset/dataset_test.py
@@ -1188,12 +1188,12 @@ def test_event_dataframe_add_property_has_expected_height(dataset_configuration,
             id='single_event_peak_velocity',
         ),
         pytest.param(
-            {'event_properties': 'position'},
+            {'event_properties': 'location'},
             {
                 'subject_id': pl.Int64,
                 **pm.events.EventDataFrame._minimal_schema,
                 'duration': pl.Int64,
-                'position': pl.List(pl.Float64),
+                'location': pl.List(pl.Float64),
             },
             id='single_event_position',
         ),
@@ -1222,8 +1222,8 @@ def test_event_dataframe_add_property_has_expected_schema(
             id='single_event_peak_velocity',
         ),
         pytest.param(
-            {'event_properties': 'position'},
-            ['position'],
+            {'event_properties': 'location'},
+            ['location'],
             id='single_event_position',
         ),
     ],
diff --git a/tests/events/event_properties_test.py b/tests/events/event_properties_test.py
index c97ce52..5e45e9d 100644
--- a/tests/events/event_properties_test.py
+++ b/tests/events/event_properties_test.py
@@ -38,7 +38,7 @@ from pymovements.events.event_properties import EVENT_PROPERTIES
             id='peak_velocity_not_2_components_raise_value_error',
         ),
         pytest.param(
-            event_properties.position,
+            event_properties.location,
             {'method': 'foo'},
             ValueError,
             ('method', 'foo', 'not', 'supported', 'mean', 'median'),
@@ -352,41 +352,41 @@ def test_property_exceptions(event_property, init_kwargs, input_df, exception, m
             id='amplitude_two_samples_xy_move',
         ),
         pytest.param(
-            event_properties.position,
+            event_properties.location,
             {'method': 'mean'},
             pl.DataFrame(
                 {'position': [[0, 0], [1, 0]]},
                 schema={'position': pl.List(pl.Float64)},
             ),
             pl.DataFrame(
-                {'position': [[0.5, 0]]},
-                schema={'position': pl.List(pl.Float64)},
+                {'location': [[0.5, 0]]},
+                schema={'location': pl.List(pl.Float64)},
             ),
             id='position_two_samples_mean',
         ),
         pytest.param(
-            event_properties.position,
+            event_properties.location,
             {'method': 'mean'},
             pl.DataFrame(
                 {'position': [[0, 0], [0, 1], [0, 3]]},
                 schema={'position': pl.List(pl.Float64)},
             ),
             pl.DataFrame(
-                {'position': [[0, 1.3333333333333333]]},
-                schema={'position': pl.List(pl.Float64)},
+                {'location': [[0, 1.3333333333333333]]},
+                schema={'location': pl.List(pl.Float64)},
             ),
             id='position_three_samples_mean',
         ),
         pytest.param(
-            event_properties.position,
+            event_properties.location,
             {'method': 'median'},
             pl.DataFrame(
                 {'position': [[0, 0], [2, 1], [3, 3]]},
                 schema={'position': pl.List(pl.Float64)},
             ),
             pl.DataFrame(
-                {'position': [[2, 1]]},
-                schema={'position': pl.List(pl.Float64)},
+                {'location': [[2, 1]]},
+                schema={'location': pl.List(pl.Float64)},
             ),
             id='position_three_samples_median',
         ),
@@ -407,7 +407,7 @@ def test_property_has_expected_result(event_property, init_kwargs, input_df, exp
         pytest.param(event_properties.dispersion, 'dispersion', id='dispersion'),
         pytest.param(event_properties.amplitude, 'amplitude', id='amplitude'),
         pytest.param(event_properties.disposition, 'disposition', id='disposition'),
-        pytest.param(event_properties.position, 'position', id='position'),
+        pytest.param(event_properties.location, 'location', id='location'),
     ],
 )
 def test_property_registered(property_function, property_function_name):