Repository: aeye-lab/pymovements
Pull request #484 (2023-08-31 10:50:08)

feat: Allow for empty lists in gaze component initializers
This allows for more comfortable usage when initializing loaded dataframes.

needed for #479 

codecov[bot]: ## [Codecov](https://app.codecov.io/gh/aeye-lab/pymovements/pull/484?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 [(`b4ed624`)](https://app.codecov.io/gh/aeye-lab/pymovements/commit/b4ed6248baed67566674eb2e52834d4a3ee97b98?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab) 100.00% compared to head [(`6a16df7`)](https://app.codecov.io/gh/aeye-lab/pymovements/pull/484?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      #484   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           48        48           
  Lines         2080      2080           
  Branches       502       502           
=========================================
  Hits          2080      2080           
```


| [Files Changed](https://app.codecov.io/gh/aeye-lab/pymovements/pull/484?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab) | Coverage Δ | |
|---|---|---|
| [src/pymovements/gaze/gaze\_dataframe.py](https://app.codecov.io/gh/aeye-lab/pymovements/pull/484?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab#diff-c3JjL3B5bW92ZW1lbnRzL2dhemUvZ2F6ZV9kYXRhZnJhbWUucHk=) | `100.00% <100.00%> (ø)` | |


</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/aeye-lab/pymovements/pull/484?src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab).   
:loudspeaker: Have feedback on the report? [Share it here](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/gaze/gaze_dataframe.py b/src/pymovements/gaze/gaze_dataframe.py
index 79c9945..0418525 100644
--- a/src/pymovements/gaze/gaze_dataframe.py
+++ b/src/pymovements/gaze/gaze_dataframe.py
@@ -96,13 +96,21 @@ class GazeDataFrame:
         time_column:
             The name if the timestamp column in the input data frame.
         pixel_columns:
-            The name of the pixel position columns in the input data frame.
+            The name of the pixel position columns in the input data frame. These columns will be
+            nested into the column ``pixel``. If the list is empty or None, the nested ``pixel``
+            column will not be created.
         position_columns:
-            The name of the dva position columns in the input data frame.
+            The name of the dva position columns in the input data frame. These columns will be
+            nested into the column ``position``. If the list is empty or None, the nested
+            ``position`` column will not be created.
         velocity_columns:
-            The name of the dva velocity columns in the input data frame.
+            The name of the velocity columns in the input data frame. These columns will be nested
+            into the column ``velocity``. If the list is empty or None, the nested ``velocity``
+            column will not be created.
         acceleration_columns:
-            The name of the dva acceleration columns in the input data frame.
+            The name of the acceleration columns in the input data frame. These columns will be
+            nested into the column ``acceleration``. If the list is empty or None, the nested
+            ``acceleration`` column will not be created.
 
         Notes
         -----
@@ -115,6 +123,7 @@ class GazeDataFrame:
 
         The supported number of component columns with the expected order are:
 
+        * zero columns: No nested component column will be created.
         * two columns: monocular data; expected order: x-component, y-component
         * four columns: binocular data; expected order: x-component left eye, y-component left eye,
           x-component right eye, y-component right eye,
@@ -173,7 +182,7 @@ class GazeDataFrame:
             self.frame = self.frame.rename({time_column: 'time'})
 
         n_components = None
-        if pixel_columns is not None:
+        if pixel_columns:
             _check_component_columns(
                 frame=self.frame,
                 pixel_columns=pixel_columns,
@@ -184,7 +193,7 @@ class GazeDataFrame:
             )
             n_components = len(pixel_columns)
 
-        if position_columns is not None:
+        if position_columns:
             _check_component_columns(
                 frame=self.frame,
                 position_columns=position_columns,
@@ -196,7 +205,7 @@ class GazeDataFrame:
             )
             n_components = len(position_columns)
 
-        if velocity_columns is not None:
+        if velocity_columns:
             _check_component_columns(
                 frame=self.frame,
                 velocity_columns=velocity_columns,
@@ -208,7 +217,7 @@ class GazeDataFrame:
             )
             n_components = len(velocity_columns)
 
-        if acceleration_columns is not None:
+        if acceleration_columns:
             _check_component_columns(
                 frame=self.frame,
                 acceleration_columns=acceleration_columns,


Test patch:
diff --git a/tests/gaze/gaze_init_test.py b/tests/gaze/gaze_init_test.py
index 12b9091..efbb593 100644
--- a/tests/gaze/gaze_init_test.py
+++ b/tests/gaze/gaze_init_test.py
@@ -44,6 +44,18 @@ from pymovements.gaze.gaze_dataframe import GazeDataFrame
             id='empty_df_with_schema_no_component_columns',
         ),
 
+        pytest.param(
+            {
+                'data': pl.DataFrame(schema={'abc': pl.Int64}),
+                'pixel_columns': [],
+                'position_columns': [],
+                'velocity_columns': [],
+                'acceleration_columns': [],
+            },
+            pl.DataFrame(schema={'abc': pl.Int64}),
+            id='empty_df_with_schema_all_component_columns_empty_lists',
+        ),
+
         pytest.param(
             {
                 'data': pl.DataFrame(schema={'x': pl.Float64, 'y': pl.Float64}),
@@ -681,16 +693,6 @@ def test_init_gaze_dataframe_has_expected_frame(init_kwargs, expected_frame):
             id='pixel_columns_str',
         ),
 
-        pytest.param(
-            {
-                'data': pl.DataFrame(schema={'x': pl.Float64, 'y': pl.Float64}),
-                'pixel_columns': [],
-            },
-            ValueError,
-            'pixel_columns must contain either 2, 4 or 6 columns, but has 0',
-            id='pixel_columns_empty_list',
-        ),
-
         pytest.param(
             {
                 'data': pl.DataFrame(schema={'x': pl.Float64, 'y': pl.Float64}),
@@ -800,16 +802,6 @@ def test_init_gaze_dataframe_has_expected_frame(init_kwargs, expected_frame):
             id='position_columns_str',
         ),
 
-        pytest.param(
-            {
-                'data': pl.DataFrame(schema={'x': pl.Float64, 'y': pl.Float64}),
-                'position_columns': [],
-            },
-            ValueError,
-            'position_columns must contain either 2, 4 or 6 columns, but has 0',
-            id='position_columns_empty_list',
-        ),
-
         pytest.param(
             {
                 'data': pl.DataFrame(schema={'x': pl.Float64, 'y': pl.Float64}),
@@ -919,16 +911,6 @@ def test_init_gaze_dataframe_has_expected_frame(init_kwargs, expected_frame):
             id='velocity_columns_str',
         ),
 
-        pytest.param(
-            {
-                'data': pl.DataFrame(schema={'x_vel': pl.Float64, 'y_vel': pl.Float64}),
-                'velocity_columns': [],
-            },
-            ValueError,
-            'velocity_columns must contain either 2, 4 or 6 columns, but has 0',
-            id='velocity_columns_empty_list',
-        ),
-
         pytest.param(
             {
                 'data': pl.DataFrame(schema={'x_vel': pl.Float64, 'y_vel': pl.Float64}),
@@ -1041,16 +1023,6 @@ def test_init_gaze_dataframe_has_expected_frame(init_kwargs, expected_frame):
             id='acceleration_columns_str',
         ),
 
-        pytest.param(
-            {
-                'data': pl.DataFrame(schema={'x_acc': pl.Float64, 'y_acc': pl.Float64}),
-                'acceleration_columns': [],
-            },
-            ValueError,
-            'acceleration_columns must contain either 2, 4 or 6 columns, but has 0',
-            id='acceleration_columns_empty_list',
-        ),
-
         pytest.param(
             {
                 'data': pl.DataFrame(schema={'x_acc': pl.Float64, 'y_acc': pl.Float64}),