Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Store metadata from ASC in experiment metadata #884

Merged
merged 25 commits into from
Nov 14, 2024
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/pymovements/dataset/dataset_files.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(

Check warning on line 380 in src/pymovements/dataset/dataset_files.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/dataset/dataset_files.py#L380

Added line #L380 was not covered by tests
filepath,
experiment=definition.experiment,
add_columns=add_columns,
Expand Down
93 changes: 86 additions & 7 deletions src/pymovements/gaze/io.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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:
dkrako marked this conversation as resolved.
Show resolved Hide resolved
"""Initialize a :py:class:`pymovements.gaze.gaze_dataframe.GazeDataFrame`.

Parameters
Expand All @@ -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)
┌─────────┬───────┬────────────────┐
Expand All @@ -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
dkrako marked this conversation as resolved.
Show resolved Hide resolved
1000.0
"""
if isinstance(patterns, str):
Expand Down Expand Up @@ -360,6 +362,83 @@
for fileinfo_key, fileinfo_dtype in column_schema_overrides.items()
])

# Convert time column to milliseconds.
gaze_data = gaze_data.with_columns([

Check warning on line 366 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L366

Added line #L366 was not covered by tests
pl.col('time').cast(pl.Int64).alias('time_ms'),
])

if experiment is None:
experiment = Experiment()

Check warning on line 371 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L371

Added line #L371 was not covered by tests
if experiment.screen is None:
saeub marked this conversation as resolved.
Show resolved Hide resolved
experiment.screen = Screen()

Check warning on line 373 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L373

Added line #L373 was not covered by tests
if experiment.eyetracker is None:
saeub marked this conversation as resolved.
Show resolved Hide resolved
experiment.eyetracker = EyeTracker()

Check warning on line 375 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L375

Added line #L375 was not covered by tests

# Resolution comparison with ASCII file and experiment
if metadata['resolution'] == (experiment.screen.height_px, experiment.screen.width_px):
pass

Check warning on line 379 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L379

Added line #L379 was not covered by tests
if (experiment.screen.height_px, experiment.screen.width_px) is None:
experiment.screen.height_px, experiment.screen.width_px = metadata['resolution']

Check warning on line 381 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L381

Added line #L381 was not covered by tests

if metadata['resolution'] != (experiment.screen.height_px, experiment.screen.width_px):
raise ValueError(

Check warning on line 384 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L384

Added line #L384 was not covered by tests
dkrako marked this conversation as resolved.
Show resolved Hide resolved
f"Ascii file says resolution should be this: {metadata['resolution']}. "
f'But resolution provided is this: '
f'({experiment.screen.height_px}, {experiment.screen.width_px})',
)

# Sample rate comparison between metadata and eyetracker metadata
if metadata['sampling_rate'] != experiment.eyetracker.sampling_rate:
raise ValueError(

Check warning on line 392 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L392

Added line #L392 was not covered by tests
f"Ascii file says sampling rate should be this: {metadata['sampling_rate']}. "
f'But sampling rate provided is this: {experiment.eyetracker.sampling_rate}',
)

if experiment.eyetracker.sampling_rate is None:
experiment.eyetracker.sampling_rate = metadata['sampling_rate']

Check warning on line 398 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L398

Added line #L398 was not covered by tests

# Left Eye or Right Eye

# left Eye or right Eye
if metadata['traked_eye'] == 'R' and not experiment.eyetracker.right:
raise ValueError(

Check warning on line 404 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L404

Added line #L404 was not covered by tests
f"Ascii file says it is: {metadata['tracked_eye']}. "
f'But the eye used by the experiment is: {experiment.eyetracker.right}',
)

if experiment.eyetracker.right is None:
experiment.eyetracker.right = metadata['traked_eye']

Check warning on line 410 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L410

Added line #L410 was not covered by tests

if metadata['traked_eye'] == 'L' and not experiment.eyetracker.left:
raise ValueError(

Check warning on line 413 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L413

Added line #L413 was not covered by tests
f"Ascii file says it is: {metadata['tracked_eye']}. "
f'But the eye used by the experiment is: {experiment.eyetracker.left}',
)

if experiment.eyetracker.left is None:
experiment.eyetracker.left = metadata['traked_eye']

Check warning on line 419 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L419

Added line #L419 was not covered by tests

# Cheking Mount configration
if metadata['mount_configuration']['mount_type'] != experiment.eyetracker.mount:
raise ValueError(

Check warning on line 423 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L423

Added line #L423 was not covered by tests
f'Ascii file says mount config should be this: '
f"{metadata['mount_configuration']['mount_type']}. "
f'But mount config provided is: {experiment.eyetracker.mount}',
)

if experiment.eyetracker.mount is None:
experiment.eyetracker.mount = metadata['mount_configuration']['mount_type']

Check warning on line 430 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L430

Added line #L430 was not covered by tests

# model check git
if metadata['model'] != experiment.eyetracker.model:
raise ValueError(

Check warning on line 434 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L434

Added line #L434 was not covered by tests
dkrako marked this conversation as resolved.
Show resolved Hide resolved
f"Ascii file says model should be this: {metadata['model']}. "
f'But model provided is: {experiment.eyetracker.model}',
)

if experiment.eyetracker.model is None:
experiment.eyetracker.model = metadata['model']

Check warning on line 440 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L440

Added line #L440 was not covered by tests

# Create gaze data frame.
gaze_df = GazeDataFrame(
gaze_data,
Expand All @@ -368,7 +447,7 @@
time_unit='ms',
pixel_columns=['x_pix', 'y_pix'],
)
return gaze_df, metadata
return gaze_df

Check warning on line 450 in src/pymovements/gaze/io.py

View check run for this annotation

Codecov / codecov/patch

src/pymovements/gaze/io.py#L450

Added line #L450 was not covered by tests


def from_ipc(
Expand Down
2 changes: 1 addition & 1 deletion tests/functional/gaze_file_processing_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
54 changes: 17 additions & 37 deletions tests/unit/gaze/io/asc_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -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'),
[
Expand All @@ -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)
saeub marked this conversation as resolved.
Show resolved Hide resolved
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'
36 changes: 36 additions & 0 deletions tests/unit/utils/parsing_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -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',
[
Expand Down
Loading