feat: Store metadata from ASC in experiment metadata

src/pymovements/dataset/dataset_files.py

@@ -377,7 +377,7 @@ def load_gaze_file(
             column_schema_overrides=definition.filename_format_schema_overrides['gaze'],
         )
     elif filepath.suffix == '.asc':
-        gaze_df, _ = from_asc(
+        gaze_df = from_asc(
             filepath,
             experiment=definition.experiment,
             add_columns=add_columns,

src/pymovements/gaze/io.py

@@ -25,8 +25,10 @@
 
 import polars as pl
 
-from pymovements.gaze import Experiment  # pylint: disable=cyclic-import
+from pymovements.gaze.experiment import Experiment
+from pymovements.gaze.eyetracker import EyeTracker
 from pymovements.gaze.gaze_dataframe import GazeDataFrame  # pylint: disable=cyclic-import
+from pymovements.gaze.screen import Screen
 from pymovements.utils.parsing import parse_eyelink
 
 
@@ -277,7 +279,7 @@
         experiment: Experiment | None = None,
         add_columns: dict[str, str] | None = None,
         column_schema_overrides: dict[str, Any] | None = None,
-) -> tuple[GazeDataFrame, dict[str, Any]]:
+) -> GazeDataFrame:
     """Initialize a :py:class:`pymovements.gaze.gaze_dataframe.GazeDataFrame`.
 
     Parameters
@@ -303,16 +305,16 @@
 
     Returns
     -------
-    tuple[GazeDataFrame, dict[str, Any]]
-        The gaze data frame and a metadata dictionary read from the asc file.
+    GazeDataFrame
+        The gaze data frame read from the asc file.
 
     Examples
     --------
     Let's assume we have an EyeLink asc file stored at `tests/files/eyelink_monocular_example.asc`.
     We can then load the data into a ``GazeDataFrame``:
 
     >>> from pymovements.gaze.io import from_asc
-    >>> gaze, metadata = from_asc(file='tests/files/eyelink_monocular_example.asc')
+    >>> gaze = from_asc(file='tests/files/eyelink_monocular_example.asc')
     >>> gaze.frame
     shape: (16, 3)
     ┌─────────┬───────┬────────────────┐
@@ -332,7 +334,7 @@
     │ 2339290 ┆ 618.0 ┆ [637.6, 531.4] │
     │ 2339291 ┆ 618.0 ┆ [637.3, 531.2] │
     └─────────┴───────┴────────────────┘
-    >>> metadata['sampling_rate']
+    >>> gaze.experiment.eyetracker.sampling_rate
     1000.0
     """
     if isinstance(patterns, str):
@@ -360,6 +362,98 @@
             for fileinfo_key, fileinfo_dtype in column_schema_overrides.items()
         ])
 
+    if experiment is None:
+        experiment = Experiment(sampling_rate=metadata['sampling_rate'])
+    if experiment.screen is None:
+        experiment.screen = Screen()
+    if experiment.eyetracker is None:
+        experiment.eyetracker = EyeTracker()
+
+    # Resolution comparison with ASCII file and experiment
+
+    if experiment.screen.width_px is None or experiment.screen.height_px is None:
+        experiment.screen.width_px, experiment.screen.height_px = metadata['resolution']
+
+    if metadata['resolution'] != (experiment.screen.width_px, experiment.screen.height_px):
+        raise ValueError(
+            f"Ascii file says resolution should be this: {metadata['resolution']}. "
+            f'But resolution provided is this: '
+            f'({experiment.screen.width_px}, {experiment.screen.height_px})',
+        )
+
+    # Sample rate comparison between metadata and eyetracker metadata
+    if experiment.eyetracker.sampling_rate is None:
+        experiment.eyetracker.sampling_rate = metadata['sampling_rate']
+    if metadata['sampling_rate'] != experiment.eyetracker.sampling_rate:
+        raise ValueError(
+            f"Ascii file says sampling rate should be this: {metadata['sampling_rate']}. "
+            f'But sampling rate provided is this: {experiment.eyetracker.sampling_rate}',
+        )
+
+
+# Left Eye or Right Eye
+
+    # left Eye or right Eye
+    if experiment.eyetracker.right is None:
+        experiment.eyetracker.right = 'R' in metadata['tracked_eye']
+
+    if metadata['tracked_eye'] == 'R' and not experiment.eyetracker.right:
+        raise ValueError(
+            f"Ascii file says it is: {metadata['tracked_eye']}. "
+            f'But the eye used by the experiment is: {experiment.eyetracker.right}',
+        )
+
+    if experiment.eyetracker.left is None:
+        experiment.eyetracker.left = 'L' in metadata['tracked_eye']
+
+    if metadata['tracked_eye'] == 'L' and not experiment.eyetracker.left:
+        raise ValueError(
+            f"Ascii file says it is: {metadata['tracked_eye']}. "
+            f'But the eye used by the experiment is: {experiment.eyetracker.left}',
+        )
+
+    # Cheking Mount configration
+    if experiment.eyetracker.mount is None:
+        experiment.eyetracker.mount = metadata['mount_configuration']['mount_type']
+
+    if metadata['mount_configuration']['mount_type'] != experiment.eyetracker.mount:
+        raise ValueError(
+            f'Ascii file says mount config should be this: '
+            f"{metadata['mount_configuration']['mount_type']}. "
+            f'But mount config provided is: {experiment.eyetracker.mount}',
+        )
+
+    # model check git
+    if experiment.eyetracker.model is None:
+        experiment.eyetracker.model = metadata['model']
+
+    if metadata['model'] != experiment.eyetracker.model:
+        raise ValueError(
+            f"Ascii file says model should be this: {metadata['model']}. "
+            f'But model provided is: {experiment.eyetracker.model}',
+        )
+
+    if experiment.eyetracker.version is None:
+        experiment.eyetracker.version = metadata['version_number']
+
+    if metadata['version_number'] != experiment.eyetracker.version:
+        raise ValueError(
+            f"Ascii file says version should be this: {metadata['version_number']}. "
+            f'But version provided is: {experiment.eyetracker.version}',
+        )
+
+    asc_says_eyelink = 'EyeLink' in metadata['model']
+    if experiment.eyetracker.vendor is None:
+        if asc_says_eyelink:
+            experiment.eyetracker.vendor = 'EyeLink'
+
+    user_says_eyelink = experiment.eyetracker.vendor == 'EyeLink'
+    if asc_says_eyelink != user_says_eyelink:
+        raise ValueError(
+            f"Ascii file says model is: {metadata['model']}. "
+            f'But vendor provided is: {experiment.eyetracker.vendor}',
+        )
+
     # Create gaze data frame.
     gaze_df = GazeDataFrame(
         gaze_data,
@@ -368,7 +462,7 @@
         time_unit='ms',
         pixel_columns=['x_pix', 'y_pix'],
     )
-    return gaze_df, metadata
+    return gaze_df
 
 
 def from_ipc(

tests/functional/gaze_file_processing_test.py

@@ -157,7 +157,7 @@ def test_gaze_file_processing(gaze_from_kwargs):
     elif file_extension in {'.feather', '.ipc'}:
         gaze = pm.gaze.from_ipc(**gaze_from_kwargs)
     elif file_extension == '.asc':
-        gaze, _ = pm.gaze.from_asc(**gaze_from_kwargs)
+        gaze = pm.gaze.from_asc(**gaze_from_kwargs)
 
     assert gaze is not None
 

tests/unit/gaze/io/asc_test.py

@@ -131,47 +131,11 @@
     ],
 )
 def test_from_asc_has_shape_and_schema(kwargs, expected_frame):
-    gaze, _ = pm.gaze.from_asc(**kwargs)
+    gaze = pm.gaze.from_asc(**kwargs)
 
     assert_frame_equal(gaze.frame, expected_frame, check_column_order=False)
 
 
-@pytest.mark.parametrize(
-    ('kwargs', 'expected_metadata'),
-    [
-        pytest.param(
-            {
-                'file': 'tests/files/eyelink_monocular_example.asc',
-                'metadata_patterns': [
-                    {'pattern': r'!V TRIAL_VAR SUBJECT_ID (?P<subject_id>-?\d+)'},
-                    r'!V TRIAL_VAR STIMULUS_COMBINATION_ID (?P<stimulus_combination_id>.+)',
-                ],
-            },
-            {
-                'subject_id': '-1',
-                'stimulus_combination_id': 'start',
-            },
-            id='eyelink_asc_metadata_patterns',
-        ),
-        pytest.param(
-            {
-                'file': 'tests/files/eyelink_monocular_example.asc',
-                'metadata_patterns': [r'inexistent pattern (?P<value>-?\d+)'],
-            },
-            {
-                'value': None,
-            },
-            id='eyelink_asc_metadata_pattern_not_found',
-        ),
-    ],
-)
-def test_from_asc_metadata_patterns(kwargs, expected_metadata):
-    _, metadata = pm.gaze.from_asc(**kwargs)
-
-    for key, value in expected_metadata.items():
-        assert metadata[key] == value
-
-
 @pytest.mark.parametrize(
     ('kwargs', 'exception', 'message'),
     [
@@ -192,3 +156,16 @@ def test_from_asc_raises_exception(kwargs, exception, message):
 
     msg, = excinfo.value.args
     assert msg == message
+
+
+def test_from_asc_fills_in_experiment_metadata():
+    gaze = pm.gaze.from_asc('tests/files/eyelink_monocular_example.asc', experiment=None)
+    assert gaze.experiment.screen.width_px == 1280
+    assert gaze.experiment.screen.height_px == 1024
+    assert gaze.experiment.eyetracker.sampling_rate == 1000.0
+    assert gaze.experiment.eyetracker.left is True
+    assert gaze.experiment.eyetracker.right is False
+    assert gaze.experiment.eyetracker.model == 'EyeLink Portable Duo'
+    assert gaze.experiment.eyetracker.version == '6.12'
+    assert gaze.experiment.eyetracker.vendor == 'EyeLink'
+    assert gaze.experiment.eyetracker.mount == 'Desktop'

tests/unit/utils/parsing_test.py

@@ -206,6 +206,42 @@ def test_parse_eyelink(tmp_path):
     assert metadata == EXPECTED_METADATA
 
 
+@pytest.mark.parametrize(
+    ('kwargs', 'expected_metadata'),
+    [
+        pytest.param(
+            {
+                'filepath': 'tests/files/eyelink_monocular_example.asc',
+                'metadata_patterns': [
+                    {'pattern': r'!V TRIAL_VAR SUBJECT_ID (?P<subject_id>-?\d+)'},
+                    r'!V TRIAL_VAR STIMULUS_COMBINATION_ID (?P<stimulus_combination_id>.+)',
+                ],
+            },
+            {
+                'subject_id': '-1',
+                'stimulus_combination_id': 'start',
+            },
+            id='eyelink_asc_metadata_patterns',
+        ),
+        pytest.param(
+            {
+                'filepath': 'tests/files/eyelink_monocular_example.asc',
+                'metadata_patterns': [r'inexistent pattern (?P<value>-?\d+)'],
+            },
+            {
+                'value': None,
+            },
+            id='eyelink_asc_metadata_pattern_not_found',
+        ),
+    ],
+)
+def test_from_asc_metadata_patterns(kwargs, expected_metadata):
+    _, metadata = pm.utils.parsing.parse_eyelink(**kwargs)
+
+    for key, value in expected_metadata.items():
+        assert metadata[key] == value
+
+
 @pytest.mark.parametrize(
     'patterns',
     [