feat: Store metadata from ASC in experiment metadata

src/pymovements/dataset/dataset_files.py

@@ -377,7 +377,7 @@
             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,7 +25,9 @@
 
 import polars as pl
 
-from pymovements.gaze import Experiment  # pylint: disable=cyclic-import
+from pymovements.gaze import Experiment
+from pymovements.gaze import EyeTracker
+from pymovements.gaze import Screen
 from pymovements.gaze.gaze_dataframe import GazeDataFrame  # pylint: disable=cyclic-import
 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.eye_tracker.sampling_rate
     1000.0
     """
     if isinstance(patterns, str):
@@ -360,6 +362,95 @@
             for fileinfo_key, fileinfo_dtype in column_schema_overrides.items()
         ])
 
+    # Convert time column to milliseconds.
+    gaze_data = gaze_data.with_columns([
+        pl.col('time').cast(pl.Int64).alias('time_ms'),
+    ])
+
+    if experiment is None:
+        experiment = Experiment()
+    if experiment.screen is None:
+        experiment.screen = Screen()
+    if experiment.eyetracker is None:
+        experiment.eyetracker = EyeTracker()
+
+    # resolution compariosn with ascii file and experiment
+    if metadata['resolution'] == (experiment.screen.height_px, experiment.screen.width_px):
+        pass
+    elif (experiment.screen.height_px, experiment.screen.width_px) is None:
+        experiment.screen.height_px, experiment.screen.width_px = metadata['resolution']
+
+    else:
+        raise ValueError(
+            f"Ascii file says resolution should be this: {
+                metadata['resolution']
+            }. But resolution provided this: {
+                experiment.screen.height_px,
+                experiment.screen.width_px
+            }",
+        )
+
+    # sample rate comparion between metadata and eyetracker metadata
+    if metadata['sampling_rate'] != experiment.eyetracker.sampling_rate:
+        raise ValueError(
+            f"Ascii file says sampling rate should be this: {
+                metadata['sampling_rate']
+            }. But sampling rate provided this: {
+                experiment.eyetracker.sampling_rate
+            }",
+        )
+    elif experiment.eyetracker.sampling_rate is None:
+        experiment.eyetracker.sampling_rate = metadata['sampling_rate']
+
+    else:
+        pass
+    # left Eye or right Eye
+    if metadata['traked_eye'] == 'R' and not experiment.eyetracker.right:
+        raise ValueError(
+            f"Ascii file syas its is:{
+                metadata['traked_eye']
+            }. But eye was used by experiment is :{
+                experiment.eyetracker.right
+            }",
+        )
+    elif experiment.eyetracker.right is None:
+        experiment.eyetracker.right = metadata['traked_eye']
+
+    if metadata['traked_eye'] == 'L' and not experiment.eyetracker.left:
+        raise ValueError(
+            f"Ascii file syas its is:{
+                metadata['traked_eye']
+            }. But eye was used by experiment is :{
+                experiment.eyetracker.left
+            }",
+        )
+    elif experiment.eyetracker.left is None:
+        experiment.eyetracker.left = metadata['traked_eye']
+
+    # Cheking Mount configration
+    if metadata['mount_configuration']['mount_type'] != experiment.eyetracker.mount:
+        raise ValueError(
+            f"Ascii file says mount config should be this: {
+                metadata['mount_configuration']['mount_type']
+            }. But mount config provided this: {
+                experiment.eyetracker.mount
+            }",
+        )
+    elif experiment.eyetracker.mount is None:
+        experiment.eyetracker.mount = metadata['mount_configuration']['mount_type']
+
+    # model check git
+    if metadata['model'] != experiment.eyetracker.model:
+        raise ValueError(
+            f"Ascii file says model should be this: {
+                metadata['model']
+            }. But model provided this: {
+                experiment.eyetracker.model
+            }",
+        )
+    elif experiment.eyetracker.model is None:
+        experiment.eyetracker.model = metadata['model']
+
     # Create gaze data frame.
     gaze_df = GazeDataFrame(
         gaze_data,
@@ -368,7 +459,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,19 @@ 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
+        == 'EYELINK II CL v6.12 Feb  1 2018 (EyeLink Portable Duo)'
+    )
+    assert gaze.experiment.eyetracker.vendor == 'SR Research'
+    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',
     [