feat(dataset): Add aliases detect() and compute_properties() (#433)

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.
 

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)