feat: Add __str__() methods to EventDataFrame and GazeDataFrame (#727)

aeye-lab · May 24, 2024 · cb32c39 · cb32c39
1 parent 38e93da
commit cb32c39
Show file tree

Hide file tree

Showing 11 changed files with 76 additions and 34 deletions.
diff --git a/docs/source/tutorials/detecting-events.ipynb b/docs/source/tutorials/detecting-events.ipynb
@@ -85,7 +85,7 @@
     "dataset.pix2deg()\n",
     "dataset.pos2vel('smooth')\n",
     "\n",
-    "dataset.gaze[0].frame.head()"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -141,7 +141,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {

diff --git a/docs/source/tutorials/event-properties.ipynb b/docs/source/tutorials/event-properties.ipynb
@@ -84,7 +84,7 @@
     "\n",
     "dataset.detect_events('microsaccades')\n",
     "\n",
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {
@@ -118,7 +118,7 @@
    "source": [
     "dataset.compute_event_properties(\"peak_velocity\")\n",
     "\n",
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {
@@ -140,7 +140,7 @@
    "source": [
     "dataset.compute_event_properties([\"amplitude\", \"dispersion\"])\n",
     "\n",
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {

diff --git a/docs/source/tutorials/heatmap.ipynb b/docs/source/tutorials/heatmap.ipynb
@@ -81,7 +81,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dataset.gaze[5].frame"
+    "dataset.gaze[5]"
    ]
   },
   {

diff --git a/docs/source/tutorials/local-dataset.ipynb b/docs/source/tutorials/local-dataset.ipynb
@@ -357,7 +357,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dataset.gaze[0].frame"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -377,7 +377,7 @@
    "source": [
     "dataset.pix2deg()\n",
     "\n",
-    "dataset.gaze[0].frame"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -397,7 +397,7 @@
    "source": [
     "dataset.pos2vel(method='savitzky_golay', degree=2, window_length=7)\n",
     "\n",
-    "dataset.gaze[0].frame"
+    "dataset.gaze[0]"
    ]
   }
  ],

diff --git a/docs/source/tutorials/plot-main-sequence.ipynb b/docs/source/tutorials/plot-main-sequence.ipynb
@@ -105,7 +105,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dataset.gaze[0].frame.head()"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -162,7 +162,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {

diff --git a/docs/source/tutorials/preprocessing-raw-data.ipynb b/docs/source/tutorials/preprocessing-raw-data.ipynb
@@ -98,7 +98,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dataset.gaze[0].frame.head()"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -135,7 +135,7 @@
    "source": [
     "dataset.pix2deg()\n",
     "\n",
-    "dataset.gaze[0].frame"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -171,7 +171,7 @@
    "source": [
     "dataset.pos2vel(method='fivepoint')\n",
     "\n",
-    "dataset.gaze[0].frame"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -199,7 +199,7 @@
    "source": [
     "dataset.pos2vel(method='savitzky_golay', degree=2, window_length=7)\n",
     "\n",
-    "dataset.gaze[0].frame"
+    "dataset.gaze[0]"
    ]
   },
   {

diff --git a/docs/source/tutorials/pymovements-in-10-minutes.ipynb b/docs/source/tutorials/pymovements-in-10-minutes.ipynb
@@ -190,7 +190,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dataset.gaze[0].frame.head()"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -251,7 +251,7 @@
    "source": [
     "dataset.pix2deg()\n",
     "\n",
-    "dataset.gaze[0].frame.head()"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -282,7 +282,7 @@
    "source": [
     "dataset.pos2vel(method='savitzky_golay', degree=2, window_length=7)\n",
     "\n",
-    "dataset.gaze[0].frame.head()"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -302,7 +302,7 @@
    "source": [
     "dataset.apply('pos2acc', degree=2, window_length=7)\n",
     "\n",
-    "dataset.gaze[0].frame.head()"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -332,7 +332,7 @@
    "source": [
     "dataset.detect_events('ivt')\n",
     "\n",
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {
@@ -405,7 +405,7 @@
    "source": [
     "dataset.compute_event_properties(\"dispersion\")\n",
     "\n",
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {
@@ -428,7 +428,7 @@
    "source": [
     "dataset.compute_event_properties([\"amplitude\", \"peak_velocity\"])\n",
     "\n",
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {

diff --git a/docs/source/tutorials/saving-loading-events.ipynb b/docs/source/tutorials/saving-loading-events.ipynb
@@ -83,7 +83,7 @@
     "dataset.pix2deg()\n",
     "dataset.pos2vel()\n",
     "\n",
-    "dataset.gaze[0].frame.head()"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -103,7 +103,7 @@
    "source": [
     "dataset.detect_events('ivt')\n",
     "\n",
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {
@@ -115,7 +115,7 @@
    "source": [
     "dataset.detect_events('microsaccades')\n",
     "\n",
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {
@@ -272,7 +272,7 @@
    "source": [
     "preprocessed_dataset.load(events=True)\n",
     "\n",
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {
@@ -303,7 +303,7 @@
     "    events_dirname='events_csv',\n",
     "    extension='csv',\n",
     ")\n",
-    "dataset.events[0].frame.head()"
+    "dataset.events[0]"
    ]
   },
   {

diff --git a/docs/source/tutorials/saving-loading-preprocessed.ipynb b/docs/source/tutorials/saving-loading-preprocessed.ipynb
@@ -83,7 +83,7 @@
     "dataset.pix2deg()\n",
     "dataset.pos2vel()\n",
     "\n",
-    "dataset.gaze[0].frame.head()"
+    "dataset.gaze[0]"
    ]
   },
   {
@@ -240,7 +240,7 @@
    "source": [
     "events_dataset.load(preprocessed=True)\n",
     "\n",
-    "events_dataset.gaze[0].frame.head()"
+    "events_dataset.gaze[0]"
    ]
   },
   {
@@ -271,7 +271,7 @@
     "    preprocessed_dirname='preprocessed_csv',\n",
     "    extension='csv',\n",
     ")\n",
-    "events_dataset.gaze[0].frame.head()"
+    "events_dataset.gaze[0]"
    ]
   },
   {

diff --git a/src/pymovements/events/frame.py b/src/pymovements/events/frame.py
@@ -56,6 +56,29 @@ class EventDataFrame:
     ValueError
         If list of onsets is passed but not a list of offsets, or vice versa, or if length of
         onsets does not match length of offsets.
+
+    Examples
+    --------
+    We define an event dataframe with given names of events and lists of onsets and offsets.
+    Durations are computed automatically.
+
+    >>> event = EventDataFrame(
+    ...    name=['fixation', 'fixation', 'fixation', 'fixation', ],
+    ...    onsets=[1988147, 1988351, 1988592, 1988788],
+    ...    offsets=[1988322, 1988546, 1988736, 1989013]
+    ... )
+    >>> event
+    shape: (4, 4)
+    ┌──────────┬─────────┬─────────┬──────────┐
+    │ name     ┆ onset   ┆ offset  ┆ duration │
+    │ ---      ┆ ---     ┆ ---     ┆ ---      │
+    │ str      ┆ i64     ┆ i64     ┆ i64      │
+    ╞══════════╪═════════╪═════════╪══════════╡
+    │ fixation ┆ 1988147 ┆ 1988322 ┆ 175      │
+    │ fixation ┆ 1988351 ┆ 1988546 ┆ 195      │
+    │ fixation ┆ 1988592 ┆ 1988736 ┆ 144      │
+    │ fixation ┆ 1988788 ┆ 1989013 ┆ 225      │
+    └──────────┴─────────┴─────────┴──────────┘
     """
 
     _minimal_schema = {'name': pl.Utf8, 'onset': pl.Int64, 'offset': pl.Int64}
@@ -268,3 +291,11 @@ def _add_minimal_schema_columns(self, df: pl.DataFrame) -> pl.DataFrame:
             ] + [pl.all()],
         )
         return df
+
+    def __str__(self: Any) -> str:
+        """Return string representation of event dataframe."""
+        return self.frame.__str__()
+
+    def __repr__(self) -> str:
+        """Return string representation of event dataframe."""
+        return self.__str__()
diff --git a/src/pymovements/gaze/gaze_dataframe.py b/src/pymovements/gaze/gaze_dataframe.py
@@ -128,7 +128,7 @@ class GazeDataFrame:
     columns, the timestamp column and the unit of the timestamps.
 
     >>> gaze = GazeDataFrame(data=df, pixel_columns=['x', 'y'], time_column='t', time_unit='ms')
-    >>> gaze.frame
+    >>> gaze
     shape: (3, 2)
     ┌──────┬────────────┐
     │ time ┆ pixel      │
@@ -159,7 +159,9 @@ class GazeDataFrame:
 
     >>> experiment = Experiment(1024, 768, 38, 30, 60, 'center', sampling_rate=100)
     >>> gaze = GazeDataFrame(data=df_no_time, experiment=experiment, pixel_columns=['x', 'y'])
-    >>> gaze.frame
+    >>> gaze
+    Experiment(sampling_rate=100, screen=Screen(width_px=1024, height_px=768, width_cm=38,
+    height_cm=30, distance_cm=60, origin=center), eyetracker=None)
     shape: (3, 2)
     ┌──────┬────────────┐
     │ time ┆ pixel      │
@@ -170,8 +172,6 @@ class GazeDataFrame:
     │ 10   ┆ [0.2, 0.2] │
     │ 20   ┆ [0.3, 0.3] │
     └──────┴────────────┘
-
-
     """
 
     def __init__(
@@ -1200,3 +1200,14 @@ def _convert_time_units(self, time_unit: str | None) -> None:
                 self.frame = self.frame.with_columns(
                     pl.col('time').cast(pl.Int64),
                 )
+
+    def __str__(self: Any) -> str:
+        """Return string representation of GazeDataFrame."""
+        if self.experiment is None:
+            return self.frame.__str__()
+
+        return self.experiment.__str__() + '\n' + self.frame.__str__()
+
+    def __repr__(self: Any) -> str:
+        """Return string representation of GazeDataFrame."""
+        return self.__str__()