eegdash 0.3.9.dev170082126__py3-none-any.whl → 0.4.0__py3-none-any.whl

eegdash/dataset/__init__.py

@@ -1,4 +1,22 @@
+"""Public API for dataset helpers and dynamically generated datasets."""
+
+from . import dataset as _dataset_mod  # triggers dynamic class registration
 from .dataset import EEGChallengeDataset
 from .registry import register_openneuro_datasets
 
-__all__ = ["EEGChallengeDataset", "register_openneuro_datasets"]
+# Re-export dynamically generated dataset classes at the package level so that
+# ``eegdash.dataset`` shows them in the API docs and users can import as
+# ``from eegdash.dataset import DSXXXXX``.
+_dyn_names = []
+for _name in getattr(_dataset_mod, "__all__", []):
+    if _name == "EEGChallengeDataset":
+        # Already imported explicitly above
+        continue
+    _obj = getattr(_dataset_mod, _name, None)
+    if _obj is not None:
+        globals()[_name] = _obj
+        _dyn_names.append(_name)
+
+__all__ = ["EEGChallengeDataset", "register_openneuro_datasets"] + _dyn_names
+
+del _dataset_mod, _name, _obj, _dyn_names

eegdash/dataset/dataset.py

@@ -1,39 +1,59 @@
-import logging
 from pathlib import Path
 
-from mne.utils import warn
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
 
 from ..api import EEGDashDataset
 from ..bids_eeg_metadata import build_query_from_kwargs
 from ..const import RELEASE_TO_OPENNEURO_DATASET_MAP, SUBJECT_MINI_RELEASE_MAP
+from ..logging import logger
 from .registry import register_openneuro_datasets
 
-logger = logging.getLogger("eegdash")
-
 
 class EEGChallengeDataset(EEGDashDataset):
-    """EEG 2025 Challenge dataset helper.
+    """A dataset helper for the EEG 2025 Challenge.
 
-    This class provides a convenient wrapper around :class:`EEGDashDataset`
-    configured for the EEG 2025 Challenge releases. It maps a given
-    ``release`` to its corresponding OpenNeuro dataset and optionally restricts
-    to the official "mini" subject subset.
+    This class simplifies access to the EEG 2025 Challenge datasets. It is a
+    specialized version of :class:`~eegdash.api.EEGDashDataset` that is
+    pre-configured for the challenge's data releases. It automatically maps a
+    release name (e.g., "R1") to the corresponding OpenNeuro dataset and handles
+    the selection of subject subsets (e.g., "mini" release).
 
     Parameters
     ----------
     release : str
-        Release name. One of ["R1", ..., "R11"].
+        The name of the challenge release to load. Must be one of the keys in
+        :const:`~eegdash.const.RELEASE_TO_OPENNEURO_DATASET_MAP`
+        (e.g., "R1", "R2", ..., "R11").
     cache_dir : str
-        Local cache directory for data files.
+        The local directory where the dataset will be downloaded and cached.
     mini : bool, default True
-        If True, restrict subjects to the challenge mini subset.
-    query : dict | None
-        Additional MongoDB-style filters to AND with the release selection.
-        Must not contain the key ``dataset``.
-    s3_bucket : str | None, default "s3://nmdatasets/NeurIPS25"
-        Base S3 bucket used to locate the challenge data.
+        If True, the dataset is restricted to the official "mini" subset of
+        subjects for the specified release. If False, all subjects for the
+        release are included.
+    query : dict, optional
+        An additional MongoDB-style query to apply as a filter. This query is
+        combined with the release and subject filters using a logical AND.
+        The query must not contain the ``dataset`` key, as this is determined
+        by the ``release`` parameter.
+    s3_bucket : str, optional
+        The base S3 bucket URI where the challenge data is stored. Defaults to
+        the official challenge bucket.
     **kwargs
-        Passed through to :class:`EEGDashDataset`.
+        Additional keyword arguments that are passed directly to the
+        :class:`~eegdash.api.EEGDashDataset` constructor.
+
+    Raises
+    ------
+    ValueError
+        If the specified ``release`` is unknown, or if the ``query`` argument
+        contains a ``dataset`` key. Also raised if ``mini`` is True and a
+        requested subject is not part of the official mini-release subset.
+
+    See Also
+    --------
+    EEGDashDataset : The base class for creating datasets from queries.
 
     """
 
@@ -123,24 +143,32 @@ class EEGChallengeDataset(EEGDashDataset):
         else:
             s3_bucket = f"{s3_bucket}/{release}_L100_bdf"
 
-        warn(
-            "\n\n"
-            "[EEGChallengeDataset] EEG 2025 Competition Data Notice:\n"
-            "-------------------------------------------------------\n"
+        message_text = Text.from_markup(
             "This object loads the HBN dataset that has been preprocessed for the EEG Challenge:\n"
-            "  - Downsampled from 500Hz to 100Hz\n"
-            "  - Bandpass filtered (0.5–50 Hz)\n"
-            "\n"
-            "For full preprocessing details, see:\n"
-            "  https://github.com/eeg2025/downsample-datasets\n"
-            "\n"
-            "IMPORTANT: The data accessed via `EEGChallengeDataset` is NOT identical to what you get from `EEGDashDataset` directly.\n"
-            "If you are participating in the competition, always use `EEGChallengeDataset` to ensure consistency with the challenge data.\n"
-            "\n",
-            UserWarning,
-            module="eegdash",
+            "  * Downsampled from 500Hz to 100Hz\n"
+            "  * Bandpass filtered (0.5-50 Hz)\n\n"
+            "For full preprocessing applied for competition details, see:\n"
+            "  [link=https://github.com/eeg2025/downsample-datasets]https://github.com/eeg2025/downsample-datasets[/link]\n\n"
+            "The HBN dataset have some preprocessing applied by the HBN team:\n"
+            "  * Re-reference (Cz Channel)\n\n"
+            "[bold red]IMPORTANT[/bold red]: The data accessed via `EEGChallengeDataset` is [u]NOT[/u] identical to what you get from [link=https://github.com/sccn/EEGDash/blob/develop/eegdash/api.py]EEGDashDataset[/link] directly.\n"
+            "If you are participating in the competition, always use `EEGChallengeDataset` to ensure consistency with the challenge data."
         )
 
+        warning_panel = Panel(
+            message_text,
+            title="[yellow]EEG 2025 Competition Data Notice[/yellow]",
+            subtitle="[cyan]Source: EEGChallengeDataset[/cyan]",
+            border_style="yellow",
+        )
+
+        # Render the panel directly to the console so it displays in IPython/terminals
+        try:
+            Console().print(warning_panel)
+        except Exception:
+            warning_message = str(message_text)
+            logger.warning(warning_message)
+
         super().__init__(
             dataset=RELEASE_TO_OPENNEURO_DATASET_MAP[release],
             query=query,