New epochs class and marker mapping

.github/workflows/main.yml

@@ -1,14 +1,20 @@
 name: PyNeon CI
 
-on: [push, pull_request]
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
 
 jobs:
-  ruff-format:
+  format:
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # to be able to push changes
 
       - name: Set up Python
         uses: actions/setup-python@v4
@@ -26,15 +32,40 @@ jobs:
         run: ruff format .
 
       - name: Commit changes if any
+        if: github.event_name == 'push' # only push changes on push events
         run: |
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
           git add .
           git commit -m "Format code with isort and ruff" || echo "No changes to commit"
           git push
 
+  tests:
+    runs-on: ${{ matrix.os }}
+    needs: format   # waits until formatting is done
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install test dependencies
+        run: pip install .[dev]
+
+      - name: Run tests
+        run: pytest tests
+
   build-docs:
     runs-on: ubuntu-latest
+    needs: format   # waits until formatting is done
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
     steps:
       - uses: actions/checkout@v4
 
@@ -44,7 +75,7 @@ jobs:
           python-version: "3.13"
 
       - name: Install Pandoc
-        run: sudo apt-get install pandoc
+        run: sudo apt-get install -y pandoc
 
       - name: Install docs dependencies
         run: pip install .[doc]
@@ -65,7 +96,6 @@ jobs:
 
       - name: Deploy (GitHub Pages)
         uses: peaceiris/actions-gh-pages@v3
-        if: github.ref == 'refs/heads/main'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: build/html

README.md

@@ -14,6 +14,8 @@ PyNeon supports both **native** (data stored in the companion device) and [**Pup
 
 Documentation for PyNeon is available at <https://ncc-brain.github.io/PyNeon/> which includes detailed references for classes and functions, as well as step-by-step tutorials presented as Jupyter notebooks.
 
+We also created a few sample datasets containing short Neon recordings for testing and tutorial purposes. These datasets can be found on [Figshare](https://doi.org/10.6084/m9.figshare.30921452). We also provide a utility function to download these sample datasets directly from PyNeon (see the [sample data tutorial](https://ncc-brain.github.io/PyNeon/tutorials/sample_data.html) for details).
+
 ## Key Features
 
 - [(Tutorial)](https://ncc-brain.github.io/PyNeon/tutorials/read_recording.html) Easy API for reading in datasets, recordings, or individual modalities of data.

pyneon/__init__.py

@@ -6,12 +6,12 @@
 install_import_hook("pyneon")
 
 from .dataset import Dataset
-from .epochs import Epochs, construct_times_df, events_to_times_df
+from .epochs import Epochs, construct_epochs_info, events_to_epochs_info
 from .events import Events
 from .recording import Recording
 from .stream import Stream
 from .utils import *
-from .video import Video
+from .video import Video, find_homographies
 
 __all__ = [
     "Dataset",
@@ -20,6 +20,7 @@
     "Events",
     "Epochs",
     "Video",
-    "construct_times_df",
-    "events_to_times_df",
+    "find_homographies",
+    "construct_epochs_info",
+    "events_to_epochs_info",
 ]

pyneon/dataset.py

@@ -28,20 +28,14 @@ class Dataset:
         ├── enrichment_info.txt
         └── sections.csv
 
-    Individual recordings will be read into :class:`pyneon.Recording` objects based on
-    ``sections.csv``. They are accessible through the ``recordings`` attribute.
+    Individual recordings will be read into :class:`pyneon.Recording` objects
+    (based on ``sections.csv``, if available) and accessible through the
+    ``recordings`` attribute.
 
     Parameters
     ----------
     dataset_dir : str or pathlib.Path
         Path to the directory containing the dataset.
-    custom : bool, optional
-        Whether to expect a custom dataset structure. If ``False``, the dataset
-        is expected to follow the standard Pupil Cloud dataset structure with a
-        ``sections.csv`` file. If True, every directory in ``dataset_dir`` is
-        considered a recording directory, and the ``sections`` attribute is
-        constructed from the ``info`` of recordings found.
-        Defaults to ``False``.
 
     Attributes
     ----------
@@ -54,22 +48,21 @@ class Dataset:
 
     """
 
-    def __init__(self, dataset_dir: str | Path, custom: bool = False):
+    def __init__(self, dataset_dir: str | Path):
         dataset_dir = Path(dataset_dir)
         if not dataset_dir.is_dir():
             raise FileNotFoundError(f"Directory not found: {dataset_dir}")
 
-        self.dataset_dir = dataset_dir
-        self.recordings = list()
+        self.dataset_dir : Path = dataset_dir
+        self.recordings : list[Recording] = list()
 
-        if not custom:
-            sections_path = dataset_dir.joinpath("sections.csv")
-            if not sections_path.is_file():
-                raise FileNotFoundError(f"sections.csv not found in {dataset_dir}")
-            self.sections = pd.read_csv(sections_path)
+        sections_path = dataset_dir / "sections.csv"
 
+        if sections_path.is_file():
+            self.sections = pd.read_csv(sections_path)
             recording_ids = self.sections["recording id"]
 
+            # Assert if recording IDs are correct
             for rec_id in recording_ids:
                 rec_id_start = rec_id.split("-")[0]
                 rec_dir = [
@@ -109,13 +102,14 @@ def __init__(self, dataset_dir: str | Path, custom: bool = False):
             for i, rec in enumerate(self.recordings):
                 sections.append(
                     {
-                        "section id": i,
+                        "section id": None,
                         "recording id": rec.recording_id,
-                        "recording name": rec.recording_id,
-                        "wearer id": rec.info["wearer_id"],
-                        "wearer name": rec.info["wearer_name"],
+                        "recording name": None,
+                        "wearer id": rec.info.get("wearer_id", None),
+                        "wearer name": rec.info.get("wearer_name", None),
                         "section start time [ns]": rec.start_time,
-                        "section end time [ns]": rec.start_time + rec.info["duration"],
+                        "section end time [ns]": rec.start_time
+                        + rec.info.get("duration", 0),
                     }
                 )