diff --git a/src/pymovements/dataset/dataset.py b/src/pymovements/dataset/dataset.py index 82a429980..0cce8fadd 100644 --- a/src/pymovements/dataset/dataset.py +++ b/src/pymovements/dataset/dataset.py @@ -455,6 +455,53 @@ def detect_events( ) return self + def detect( + self, + method: Callable[..., EventDataFrame] | str, + *, + eye: str | None = 'auto', + clear: bool = False, + verbose: bool = True, + **kwargs: Any, + ) -> Dataset: + """Detect events by applying a specific event detection method. + + Alias for :py:meth:`pymovements.Dataset.detect_events` + + Parameters + ---------- + method : EventDetectionCallable + The event detection method to be applied. + eye : str + Select which eye to choose. Valid options are ``auto``, ``left``, ``right`` or ``None``. + If ``auto`` is passed, eye is inferred in the order ``['right', 'left', 'eye']`` from + the available :py:attr:`~.Dataset.gaze` dataframe columns. + clear : bool + If ``True``, event DataFrame will be overwritten with new DataFrame instead of being + merged into the existing one. + verbose : bool + If ``True``, show progress bar. + **kwargs : + Additional keyword arguments to be passed to the event detection method. + + Raises + ------ + AttributeError + If gaze files have not been loaded yet or gaze files do not contain the right columns. + + Returns + ------- + Dataset + Returns self, useful for method cascading. + """ + return self.detect_events( + method=method, + eye=eye, + clear=clear, + verbose=verbose, + **kwargs, + ) + def compute_event_properties( self, event_properties: str | tuple[str, dict[str, Any]] @@ -498,6 +545,43 @@ def compute_event_properties( return self + def compute_properties( + self, + event_properties: str | tuple[str, dict[str, Any]] + | list[str | tuple[str, dict[str, Any]]], + name: str | None = None, + verbose: bool = True, + ) -> Dataset: + """Calculate an event property for and add it as a column to the event dataframe. + + Alias for :py:meth:`pymovements.Dataset.compute_event_properties` + + Parameters + ---------- + event_properties: + The event properties to compute. + name: + Process only events that match the name. + verbose : bool + If ``True``, show progress bar. + + Raises + ------ + InvalidProperty + If ``property_name`` is not a valid property. See + :py:mod:`pymovements.events.event_properties` for an overview of supported properties. + + Returns + ------- + Dataset + Returns self, useful for method cascading. + """ + return self.compute_event_properties( + event_properties=event_properties, + name=name, + verbose=verbose, + ) + def clear_events(self) -> Dataset: """Clear event DataFrame. diff --git a/tests/dataset/dataset_test.py b/tests/dataset/dataset_test.py index ba067abff..eed081f5c 100644 --- a/tests/dataset/dataset_test.py +++ b/tests/dataset/dataset_test.py @@ -22,6 +22,7 @@ import shutil import unittest from pathlib import Path +from unittest.mock import Mock import numpy as np import polars as pl @@ -697,6 +698,34 @@ def test_detect_events_multiple_calls( assert result_event_df.schema == expected_schema +@pytest.mark.parametrize( + 'detect_kwargs', + [ + pytest.param( + { + 'method': 'microsaccades', + 'threshold': 1, + 'eye': 'left', + 'clear': False, + 'verbose': True, + }, + id='left', + ), + ], +) +def test_detect_events_alias(dataset_configuration, detect_kwargs, monkeypatch): + dataset = pm.Dataset(**dataset_configuration['init_kwargs']) + dataset.load() + dataset.pix2deg() + dataset.pos2vel() + + mock = Mock() + monkeypatch.setattr(dataset, 'detect_events', mock) + + dataset.detect(**detect_kwargs) + mock.assert_called_with(**detect_kwargs) + + def test_detect_events_attribute_error(dataset_configuration): dataset = pm.Dataset(**dataset_configuration['init_kwargs']) dataset.load() @@ -1315,3 +1344,26 @@ def test_event_dataframe_add_property_does_not_change_length( lengths_post = [len(events_df.frame) for events_df in dataset.events] assert lengths_pre == lengths_post + + +@pytest.mark.parametrize( + 'property_kwargs', + [ + pytest.param( + { + 'event_properties': 'peak_velocity', + 'name': None, + 'verbose': True, + }, id='peak_velocity', + ), + ], +) +def test_compute_event_properties_alias(dataset_configuration, property_kwargs, monkeypatch): + dataset = pm.Dataset(**dataset_configuration['init_kwargs']) + dataset.load(preprocessed=True, events=True) + + mock = Mock() + monkeypatch.setattr(dataset, 'compute_event_properties', mock) + + dataset.compute_properties(**property_kwargs) + mock.assert_called_with(**property_kwargs)