parse metadata in utils.parsing.parse_eyelink

[dkrako]

Description of the problem

The header of an asc file has a lot of metadata which we can parse.

Description of a solution

Instead of just returning a dataframe, the function then should return a tuple of a dataframe and a dictionary with parsed info

Minimum acceptance criteria

• [x] parsing recording datetime
• [x] parse eye tracker model and version
• [x] parse tracker mount info
• [x] parse display resolution
• [x] get pupil size data type
• [x] parse sampling rate
• [x] parse filter setting
• [ ] parse TRACKING
• [ ] parse CR
• [ ] parse VEL
• [ ] parse RES
• [ ] parse HTARG
• [ ] parse INPUT
• [ ] parse BUTTONS
• [ ] parse LEFT
• [ ] parse RIGHT
• [ ] infer if monocular

Context

the eyelink_parser from eyelinker is a good reference for implementation: https://github.com/cran/eyelinker/blob/master/R/eyelink_parser.R

https://cran.r-project.org/web/packages/eyelinker/vignettes/format.html

[dkrako]

This is the current signature: https://github.com/aeye-lab/pymovements/blob/9eb46c56230cbe5deebbc7af6797745a46af1613/src/pymovements/utils/parsing.py#L110-L114

• [x] It should be changed to:

 def parse_eyelink( 
         filepath: Path | str, 
         patterns: list | None = None, 
         schema: dict | None = None, 
 ) -> tuple[pl.DataFrame, dict[str, Any]] : 

The keys of the dictionary should resemble the metadata.

• [x] In parsing.py you can create a global dictionary EYELINK_META_REGEXES: list[str] where each string will be a simple string holding the regex. The group name in the regex will then be used as a key in the output meta dictionary (e.g. SAMPLES\s+GAZE\s+LEFT\s+RATE\s+(?P<sampling_rate>[-]?\d*[.]\d*)\s+TRACKING\s+(?P<tracking>\S+)\s+FILTER\s+(?P<tracking>\d+)\s+ INPUT would write to the keys samping_rate, tracking, and filter.

• [x] Compile all the strings in EYELINK_META_REGEXES with re.compile in the parse_eyelink() method, not the global context, otherwise each pymovements import will slow down because of compiling all the regexes. (the way EYE_TRACKING_SAMPLE is defined is not optimal, compile shouldn't be done in the global context)

• [x] you can use Match.groupdict() to get the names and values of your match and put it into the output meta dictionary

• [x] Don't care about integrating this into the 'gaze.from_asc()` function yet. you can just ignore the meta tuple in that function so we can focus on parse_eyelink first

• [x] Focus on the most important metadata first, like sampling rate and display resolution, we can add more in subsequent PRs