Add sample_data module using pooch for example datasets

ethology/datasets/__init__.py

@@ -0,0 +1,3 @@
+from .sample_data import load_sample_tracking
+
+__all__ = ["load_sample_tracking"]

ethology/datasets/sample_data.py

@@ -0,0 +1,28 @@
+"""Utilities for downloading and loading example datasets for ethology.
+
+This module provides helper functions that use `pooch` to fetch
+small example datasets used in tutorials, tests, and documentation.
+"""
+
+import pooch
+
+...
+
+
+DATA_REGISTRY = pooch.create(
+    path=pooch.os_cache("ethology"),
+    base_url="https://example-dataset-url/",
+    registry={"example_tracking.csv": None},
+)
+
+
+def load_sample_tracking() -> str:
+    """Fetch a sample tracking dataset.
+
+    Returns
+    -------
+    str
+        Path to the downloaded dataset.
+
+    """
+    return DATA_REGISTRY.fetch("example_tracking.csv")

ethology/io/__init__.py

@@ -1 +1 @@
-""" Load and export `ethology` datasets."""
+"""Load and export `ethology` datasets."""

examples/approximate_subset_sum_split.py

@@ -4,6 +4,7 @@
 Split an annotations dataset by grouping variable, and compare to random
 splitting.
 """
+
 # %%
 # This example demonstrates two dataset splitting strategies:
 #

examples/coco_bbox_ethology_and_movement.py

@@ -6,7 +6,6 @@
 `movement <https://movement.neuroinformatics.dev/>`_.
 """
 
-
 # %%
 # Imports
 # -------

pyproject.toml

@@ -26,6 +26,7 @@ dependencies = [
   "torch",
   "torchvision",
   "loguru",
+  "pooch",
   "tables>=3.10.1"     # wheels compatible with MacOS ARM
 ]
 

tests/test_sample_data.py

@@ -0,0 +1,26 @@
+import os
+
+from ethology.datasets import load_sample_tracking
+
+
+def test_load_sample_tracking_returns_path():
+    """Ensure loader returns a valid file path."""
+    path = load_sample_tracking()
+
+    assert isinstance(path, str)
+    assert os.path.exists(path)
+
+
+def test_load_sample_tracking_cached():
+    """Ensure dataset is cached and not downloaded twice."""
+    path1 = load_sample_tracking()
+    path2 = load_sample_tracking()
+
+    assert path1 == path2
+
+
+def test_sample_dataset_filename():
+    """Check returned dataset filename."""
+    path = load_sample_tracking()
+
+    assert path.endswith("example_tracking.csv")

tests/test_unit/test_io_annotations/test_load_bboxes.py

@@ -485,9 +485,9 @@ def test_df_from_single_file(
         expected_n_unique_images_with_annotations,
         expected_categories=expected_category_data[0],
         expected_supercategories=expected_category_data[1],
-        expected_annots_per_image=1
-        if expected_n_unique_images_with_annotations < 5
-        else None,
+        expected_annots_per_image=(
+            1 if expected_n_unique_images_with_annotations < 5 else None
+        ),
     )
 
     # Check image shape data is present if present in the input file