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,50 @@ 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 }}
+    env:
+      PYTHONFAULTHANDLER: "1"
+    needs: format   # waits until formatting is done
+    strategy:
+      fail-fast: false
+      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
+        if: matrix.os != 'windows-latest'
+        run: pytest tests -p no:cacheprovider -p no:faulthandler -p no:unraisableexception
+
+      - name: Run tests (Windows, disable MSMF)
+        if: matrix.os == 'windows-latest'
+        env:
+          OPENCV_VIDEOIO_PRIORITY_MSMF: "0"
+        run: pytest tests -p no:cacheprovider -p no:faulthandler -p no:unraisableexception
+
   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 +85,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 +106,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

.gitignore

@@ -1,6 +1,7 @@
 # Test data
 data/
 tests/outputs/
+source/tutorials/export/
 
 # Ruff
 .ruff_cache/

README.md

@@ -1,5 +1,6 @@
 ![GitHub License](https://img.shields.io/github/license/ncc-brain/PyNeon?style=plastic)
 ![Website](https://img.shields.io/website?url=https%3A%2F%2Fncc-brain.github.io%2FPyNeon%2F&up_message=online&style=plastic&label=Documentation)
+[![PyNeon CI](https://github.com/ncc-brain/PyNeon/actions/workflows/main.yml/badge.svg)](https://github.com/ncc-brain/PyNeon/actions/workflows/main.yml)
 
 # PyNeon
 
@@ -14,14 +15,18 @@ 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 [OSF](https://doi.org/10.17605/OSF.IO/3N85H). We also provide a utility function `get_sample_data()` to download these sample datasets directly from PyNeon.
+
 ## 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.
+- Easy API for reading in datasets, recordings, or individual modalities of data.
+  - [Tutorial](https://ncc-brain.github.io/PyNeon/tutorials/read_recording_cloud.html) for reading data in Pupil Cloud format
+  - [Tutorial](https://ncc-brain.github.io/PyNeon/tutorials/read_recording_native.html) for reading data in native format
 - [(Tutorial)](https://ncc-brain.github.io/PyNeon/tutorials/interpolate_and_concat.html) Various preprocessing functions, including data cropping, interpolation,
   concatenation, etc.
 - [(Tutorial)](https://ncc-brain.github.io/PyNeon/tutorials/pupil_size_and_epoching.html) Flexible epoching of data for trial-based analysis.
 - [(Tutorial)](https://ncc-brain.github.io/PyNeon/tutorials/video.html) Methods for working with scene video, including scanpath estimation and AprilTags-based mapping.
-- [(Tutorial)](https://ncc-brain.github.io/PyNeon/tutorials/export_to_bids.html) Exportation to [Motion-BIDS](https://www.nature.com/articles/s41597-024-03559-8) (and forthcoming Eye-Tracking-BIDS) format for interoperability across the cognitive neuroscience community.
+- [(Tutorial)](https://ncc-brain.github.io/PyNeon/tutorials/export_to_bids.html) Exportation to [Motion-BIDS](https://doi.org/10.1038/s41597-024-03559-8) and [Eye-Tracking-BIDS](https://doi.org/10.64898/2026.02.03.703514) formats for interoperability across the cognitive neuroscience community.
 
 ## Installation
 

pyneon/__init__.py

@@ -1,17 +1,14 @@
 # ruff: noqa: E402
 __version__ = "0.0.1"
 
-from typeguard import install_import_hook
-
-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
+from .vis import plot_marker_layout
 
 __all__ = [
     "Dataset",
@@ -20,6 +17,8 @@
     "Events",
     "Epochs",
     "Video",
-    "construct_times_df",
-    "events_to_times_df",
+    "plot_marker_layout",
+    "find_homographies",
+    "construct_epochs_info",
+    "events_to_epochs_info",
 ]

pyneon/dataset.py

@@ -8,9 +8,10 @@
 
 class Dataset:
     """
-    Holder for multiple recordings. It reads from a directory containing a multiple
-    recordings downloaded from Pupil Cloud with the **Timeseries CSV** or
-    **Timeseries CSV and Scene Video** option. For example, a dataset with 2 recordings
+    Container for multiple recordings. Reads from a directory containing multiple
+    recordings.
+
+    For example, a dataset with 2 recordings downloaded from Pupil Cloud
     would have the following folder structure:
 
     .. code-block:: text
@@ -28,48 +29,76 @@ 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.
+    Or a dataset with multiple native recordings:
+
+    .. code-block:: text
+
+        dataset_dir/
+        ├── recording_dir_1/
+        │   ├── info.json
+        │   ├── blinks ps1.raw
+        |   ├── blinks ps1.time
+        |   ├── blinks.dtype
+        |   └── ...
+        └── recording_dir_2/
+            ├── info.json
+            ├── blinks ps1.raw
+            ├── blinks ps1.time
+            ├── blinks.dtype
+            └── ...
+
+    Individual recordings will be read into :class:`Recording` instances
+    (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
     ----------
     dataset_dir : pathlib.Path
         Path to the directory containing the dataset.
     recordings : list of Recording
-        List of :class:`pyneon.Recording` objects for each recording in the dataset.
+        List of :class:`Recording` instances for each recording in the dataset.
     sections : pandas.DataFrame
         DataFrame containing the sections of the dataset.
 
+    Examples
+    --------
+    >>> from pyneon import Dataset
+    >>> dataset = Dataset("path/to/dataset")
+    >>> print(dataset)
+
+    Dataset | 2 recordings
+
+    >>> rec = dataset.recordings[0]
+    >>> print(rec)
+
+    Data format: cloud
+    Recording ID: 56fcec49-d660-4d67-b5ed-ba8a083a448a
+    Wearer ID: 028e4c69-f333-4751-af8c-84a09af079f5
+    Wearer name: Pilot
+    Recording start time: 2025-12-18 17:13:49.460000
+    Recording duration: 8235000000 ns (8.235 s)
     """
 
-    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 = [
@@ -104,44 +133,44 @@ def __init__(self, dataset_dir: str | Path, custom: bool = False):
                         RuntimeWarning,
                     )
 
-            # Rebuild a `sections` DataFrame from the Recording objects
+            # Rebuild a `sections` DataFrame from the Recording instances
             sections = []
-            for i, rec in enumerate(self.recordings):
+            for rec in 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),
                     }
                 )
 
             self.sections = pd.DataFrame(sections)
 
     def __repr__(self):
+        """Return a string representation of the Dataset.
+
+        Returns
+        -------
+        str
+            Summary showing the number of recordings.
+        """
         return f"Dataset | {len(self.recordings)} recordings"
 
     def __len__(self):
+        """Return the number of recordings in the dataset.
+
+        Returns
+        -------
+        int
+            Number of recordings.
+        """
         return len(self.recordings)
 
     def __getitem__(self, index: int) -> Recording:
         """Get a Recording by index."""
         return self.recordings[index]
-
-    def load_enrichment(self, enrichment_dir: str | Path):
-        """
-        Load enrichment information from an enrichment directory. The directory must
-        contain an enrichment_info.txt file. Enrichment data will be parsed for each
-        recording ID and added to Recording object in the dataset.
-
-        The method is currently being developed and is not yet implemented.
-
-        Parameters
-        ----------
-        enrichment_dir : str or pathlib.Path
-            Path to the directory containing the enrichment information.
-        """
-        raise NotImplementedError("Enrichment loading is not yet implemented.")