feat!: Custom patterns for parsing logged metadata in ASC files

src/pymovements/dataset/dataset_files.py

@@ -336,7 +336,7 @@ def load_gaze_file(
             column_dtypes=definition.filename_format_dtypes,
         )
     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

@@ -268,21 +268,25 @@ def from_csv(
 def from_asc(
         file: str | Path,
         *,
-        patterns: str | list | None = 'eyelink',
+        patterns: str | list[dict[str, Any] | str] | None = 'eyelink',
+        metadata_patterns: list[dict[str, Any] | str] | None = None,
         schema: dict[str, Any] | None = None,
         experiment: Experiment | None = None,
         add_columns: dict[str, str] | None = None,
         column_dtypes: dict[str, Any] | None = None,
-) -> GazeDataFrame:
+) -> tuple[GazeDataFrame, dict[str, Any]]:
     """Initialize a :py:class:`pymovements.gaze.gaze_dataframe.GazeDataFrame`.
 
     Parameters
     ----------
     file: str | Path
         Path of IPC/feather file.
-    patterns: str | list | None
+    patterns: str | list[dict[str, Any] | str] | None
         list of patterns to match for additional columns or a key identifier of eye tracker specific
         default patterns. Supported values are: eyelink. (default: 'eyelink')
+    metadata_patterns: list[dict[str, Any] | str] | None
+        list of patterns to match for extracting metadata from custom logged messages.
+        (default: None)
     schema: dict[str, Any] | None
         Dictionary to optionally specify types of columns parsed by patterns. (default: None)
     experiment: Experiment | None
@@ -296,16 +300,16 @@ def from_asc(
 
     Returns
     -------
-    GazeDataFrame
-        The gaze data frame read from the asc file.
+    tuple[GazeDataFrame, dict[str, Any]]
+        The gaze data frame and a metadata dictionary 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 = from_asc(file='tests/files/eyelink_monocular_example.asc', patterns='eyelink')
+    >>> gaze, metadata = from_asc(file='tests/files/eyelink_monocular_example.asc')
     >>> gaze.frame
     shape: (16, 3)
     ┌─────────┬───────┬────────────────┐
@@ -323,7 +327,8 @@ def from_asc(
     │ 2339290 ┆ 618.0 ┆ [637.6, 531.4] │
     │ 2339291 ┆ 618.0 ┆ [637.3, 531.2] │
     └─────────┴───────┴────────────────┘
-
+    >>> metadata['sampling_rate']
+    1000.0
     """
     if isinstance(patterns, str):
         if patterns == 'eyelink':
@@ -333,7 +338,9 @@ def from_asc(
             raise ValueError(f"unknown pattern key '{patterns}'. Supported keys are: eyelink")
 
     # Read data.
-    gaze_data, _ = parse_eyelink(file, patterns=patterns, schema=schema)
+    gaze_data, metadata = parse_eyelink(
+        file, patterns=patterns, schema=schema, metadata_patterns=metadata_patterns,
+    )
 
     if add_columns is not None:
         gaze_data = gaze_data.with_columns([
@@ -356,7 +363,7 @@ def from_asc(
         time_unit='ms',
         pixel_columns=['x_pix', 'y_pix'],
     )
-    return gaze_df
+    return gaze_df, metadata
 
 
 def from_ipc(