feat: Raise helpful missing column error message for transforms (#542)

src/pymovements/gaze/gaze_dataframe.py

@@ -266,6 +266,33 @@ def transform(
                 _check_n_components(self.n_components)
                 kwargs['n_components'] = self.n_components
 
+            if transform_method.__name__ in {'pos2vel', 'pos2acc'}:
+                if 'position' not in self.frame.columns and 'position_column' not in kwargs:
+                    if 'pixel' in self.frame.columns:
+                        raise pl.exceptions.ColumnNotFoundError(
+                            "Neither 'position' is in the columns of the dataframe: "
+                            f'{self.frame.columns} nor is the position column specified. '
+                            "Since the dataframe has a 'pixel' column, consider running "
+                            f'pix2deg() before {transform_method.__name__}(). If you want '
+                            'to calculate pixel transformations, you can do so by using '
+                            f"{transform_method.__name__}(position_column='pixel'). "
+                            f'Available dataframe columns are {self.frame.columns}',
+                        )
+                    raise pl.exceptions.ColumnNotFoundError(
+                        "Neither 'position' is in the columns of the dataframe: "
+                        f'{self.frame.columns} nor is the position column specified. '
+                        f'Available dataframe columns are {self.frame.columns}',
+                    )
+            if transform_method.__name__ in {'pix2deg'}:
+                if 'pixel' not in self.frame.columns and 'pixel_column' not in kwargs:
+                    raise pl.exceptions.ColumnNotFoundError(
+                        "Neither 'position' is in the columns of the dataframe: "
+                        f'{self.frame.columns} nor is the pixel column specified. '
+                        'You can specify the pixel column via: '
+                        f'{transform_method.__name__}(pixel_column="name_of_your_pixel_column"). '
+                        f'Available dataframe columns are {self.frame.columns}',
+                    )
+
             if self.trial_columns is None:
                 self.frame = self.frame.with_columns(transform_method(**kwargs))
             else:

tests/gaze/gaze_transform_test.py

@@ -528,8 +528,10 @@ def test_gaze_dataframe_pix2deg_creates_position_column(data, experiment, pixel_
             },
             pl.exceptions.ColumnNotFoundError,
             (
-                'pixel\n\nError originated just after this operation:\nDF ["acceleration"]; '
-                'PROJECT */1 COLUMNS; SELECTION: "None"'
+                "Neither 'position' is in the columns of the dataframe: ['acceleration'] nor "
+                'is the pixel column specified. You can specify the pixel column via: '
+                'pix2deg(pixel_column="name_of_your_pixel_column"). Available dataframe '
+                "columns are ['acceleration']"
             ),
             id='no_pixel_column',
         ),
@@ -609,8 +611,25 @@ def test_gaze_dataframe_pos2acc_creates_acceleration_column(data, experiment, po
             },
             pl.exceptions.ColumnNotFoundError,
             (
-                'position\n\nError originated just after this operation:\nDF ["pixel"]; '
-                'PROJECT */1 COLUMNS; SELECTION: "None"'
+                "Neither 'position' is in the columns of the dataframe: ['pixel'] nor is the "
+                "position column specified. Since the dataframe has a 'pixel' column, "
+                'consider running pix2deg() before pos2acc(). If you want to calculate pixel '
+                "transformations, you can do so by using pos2acc(position_column='pixel'). "
+                "Available dataframe columns are ['pixel']"
+            ),
+            id='no_position_column',
+        ),
+        pytest.param(
+            {
+                'data': pl.from_dict({'x': [0.1], 'y': [0.2]}),
+                'experiment': pm.Experiment(1024, 768, 38, 30, 60, 'center', 1000),
+                'acceleration_columns': ['x', 'y'],
+            },
+            pl.exceptions.ColumnNotFoundError,
+            (
+                "Neither 'position' is in the columns of the dataframe: ['acceleration'] nor "
+                'is the position column specified. Available dataframe columns are '
+                "['acceleration']"
             ),
             id='no_position_column',
         ),
@@ -690,8 +709,25 @@ def test_gaze_dataframe_pos2vel_creates_velocity_column(data, experiment, positi
             },
             pl.exceptions.ColumnNotFoundError,
             (
-                'position\n\nError originated just after this operation:\nDF ["pixel"]; '
-                'PROJECT */1 COLUMNS; SELECTION: "None"'
+                "Neither 'position' is in the columns of the dataframe: ['pixel'] nor is the "
+                "position column specified. Since the dataframe has a 'pixel' column, "
+                'consider running pix2deg() before pos2vel(). If you want to calculate pixel '
+                "transformations, you can do so by using pos2vel(position_column='pixel'). "
+                "Available dataframe columns are ['pixel']"
+            ),
+            id='no_position_column',
+        ),
+        pytest.param(
+            {
+                'data': pl.from_dict({'x': [0.1], 'y': [0.2]}),
+                'experiment': pm.Experiment(1024, 768, 38, 30, 60, 'center', 1000),
+                'acceleration_columns': ['x', 'y'],
+            },
+            pl.exceptions.ColumnNotFoundError,
+            (
+                "Neither 'position' is in the columns of the dataframe: ['acceleration'] nor "
+                'is the position column specified. Available dataframe columns are '
+                "['acceleration']"
             ),
             id='no_position_column',
         ),