eegdash 0.4.0.dev153__py3-none-any.whl → 0.4.0.dev162__py3-none-any.whl

eegdash/dataset/dataset.py

@@ -12,26 +12,48 @@ from .registry import register_openneuro_datasets
 
 
 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
+        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.
 
     """
 

eegdash/dataset/dataset_summary.csv

@@ -198,7 +198,7 @@
 197,ds003751,38,38,1,128,250,19.95,4.71 GB,5057922307,0,ds003751,Healthy,other,Multisensory,Affect
 198,ds003421,80,20,1,257,1000,11.604,76.77 GB,82433418198,0,ds003421,Healthy,10-20,Multisensory,Decision-making
 199,ds002158,117,20,1,,,0.0,428.59 GB,460190030981,0,ds002158,Healthy,10-20,Visual,Affect
-200,ds004951,23,11,1,63,1000,29.563,22.00 GB,23627352274,0,ds004951,?,,Tactile,Learning
+200,ds004951,23,11,1,63,1000,29.563,22.00 GB,23627352274,0,ds004951,,,Tactile,Learning
 201,ds004802,38,38,1,65,"2048,512",0.0,29.34 GB,31504070800,0,ds004802,Other,,Visual,Affect
 202,ds004816,20,20,1,63,1000,0.0,23.31 GB,25028989553,0,ds004816,Healthy,,Visual,Attention
 203,ds005873,2850,125,1,2,256,11935.09,117.21 GB,125851664268,0,,,,,

eegdash/dataset/registry.py

@@ -14,7 +14,35 @@ def register_openneuro_datasets(
     namespace: Dict[str, Any] | None = None,
     add_to_all: bool = True,
 ) -> Dict[str, type]:
-    """Dynamically create dataset classes from a summary file."""
+    """Dynamically create and register dataset classes from a summary file.
+
+    This function reads a CSV file containing summaries of OpenNeuro datasets
+    and dynamically creates a Python class for each dataset. These classes
+    inherit from a specified base class and are pre-configured with the
+    dataset's ID.
+
+    Parameters
+    ----------
+    summary_file : str or pathlib.Path
+        The path to the CSV file containing the dataset summaries.
+    base_class : type, optional
+        The base class from which the new dataset classes will inherit. If not
+        provided, :class:`eegdash.api.EEGDashDataset` is used.
+    namespace : dict, optional
+        The namespace (e.g., `globals()`) into which the newly created classes
+        will be injected. Defaults to the local `globals()` of this module.
+    add_to_all : bool, default True
+        If True, the names of the newly created classes are added to the
+        `__all__` list of the target namespace, making them importable with
+        `from ... import *`.
+
+    Returns
+    -------
+    dict[str, type]
+        A dictionary mapping the names of the registered classes to the class
+        types themselves.
+
+    """
     if base_class is None:
         from ..api import EEGDashDataset as base_class  # lazy import
 
@@ -84,8 +112,28 @@ def register_openneuro_datasets(
     return registered
 
 
-def _generate_rich_docstring(dataset_id: str, row_series: pd.Series, base_class) -> str:
-    """Generate a comprehensive docstring for a dataset class."""
+def _generate_rich_docstring(
+    dataset_id: str, row_series: pd.Series, base_class: type
+) -> str:
+    """Generate a comprehensive, well-formatted docstring for a dataset class.
+
+    Parameters
+    ----------
+    dataset_id : str
+        The identifier of the dataset (e.g., "ds002718").
+    row_series : pandas.Series
+        A pandas Series containing the metadata for the dataset, extracted
+        from the summary CSV file.
+    base_class : type
+        The base class from which the new dataset class inherits. Used to
+        generate the "See Also" section of the docstring.
+
+    Returns
+    -------
+    str
+        A formatted docstring.
+
+    """
     # Extract metadata with safe defaults
     n_subjects = row_series.get("n_subjects", "Unknown")
     n_records = row_series.get("n_records", "Unknown")
@@ -173,7 +221,24 @@ See Also
 
 
 def _markdown_table(row_series: pd.Series) -> str:
-    """Create a reStructuredText grid table from a pandas Series."""
+    """Create a reStructuredText grid table from a pandas Series.
+
+    This helper function takes a pandas Series containing dataset metadata
+    and formats it into a reStructuredText grid table for inclusion in
+    docstrings.
+
+    Parameters
+    ----------
+    row_series : pandas.Series
+        A Series where each index is a metadata field and each value is the
+        corresponding metadata value.
+
+    Returns
+    -------
+    str
+        A string containing the formatted reStructuredText table.
+
+    """
     if row_series.empty:
         return ""
     dataset_id = row_series["dataset"]

eegdash/downloader.py

@@ -17,18 +17,62 @@ import s3fs
 from fsspec.callbacks import TqdmCallback
 
 
-def get_s3_filesystem():
-    """Returns an S3FileSystem object."""
+def get_s3_filesystem() -> s3fs.S3FileSystem:
+    """Get an anonymous S3 filesystem object.
+
+    Initializes and returns an ``s3fs.S3FileSystem`` for anonymous access
+    to public S3 buckets, configured for the 'us-east-2' region.
+
+    Returns
+    -------
+    s3fs.S3FileSystem
+        An S3 filesystem object.
+
+    """
     return s3fs.S3FileSystem(anon=True, client_kwargs={"region_name": "us-east-2"})
 
 
 def get_s3path(s3_bucket: str, filepath: str) -> str:
-    """Helper to form an AWS S3 URI for the given relative filepath."""
+    """Construct an S3 URI from a bucket and file path.
+
+    Parameters
+    ----------
+    s3_bucket : str
+        The S3 bucket name (e.g., "s3://my-bucket").
+    filepath : str
+        The path to the file within the bucket.
+
+    Returns
+    -------
+    str
+        The full S3 URI (e.g., "s3://my-bucket/path/to/file").
+
+    """
     return f"{s3_bucket}/{filepath}"
 
 
-def download_s3_file(s3_path: str, local_path: Path, s3_open_neuro: bool):
-    """Download function that gets the raw EEG data from S3."""
+def download_s3_file(s3_path: str, local_path: Path, s3_open_neuro: bool) -> Path:
+    """Download a single file from S3 to a local path.
+
+    Handles the download of a raw EEG data file from an S3 bucket, caching it
+    at the specified local path. Creates parent directories if they do not exist.
+
+    Parameters
+    ----------
+    s3_path : str
+        The full S3 URI of the file to download.
+    local_path : pathlib.Path
+        The local file path where the downloaded file will be saved.
+    s3_open_neuro : bool
+        A flag indicating if the S3 bucket is the OpenNeuro main bucket, which
+        may affect path handling.
+
+    Returns
+    -------
+    pathlib.Path
+        The local path to the downloaded file.
+
+    """
     filesystem = get_s3_filesystem()
     if not s3_open_neuro:
         s3_path = re.sub(r"(^|/)ds\d{6}/", r"\1", s3_path, count=1)
@@ -51,8 +95,31 @@ def download_dependencies(
     dataset_folder: Path,
     record: dict[str, Any],
     s3_open_neuro: bool,
-):
-    """Download all BIDS dependency files from S3 and cache them locally."""
+) -> None:
+    """Download all BIDS dependency files from S3.
+
+    Iterates through a list of BIDS dependency files, downloads each from the
+    specified S3 bucket, and caches them in the appropriate local directory
+    structure.
+
+    Parameters
+    ----------
+    s3_bucket : str
+        The S3 bucket to download from.
+    bids_dependencies : list of str
+        A list of dependency file paths relative to the S3 bucket root.
+    bids_dependencies_original : list of str
+        The original dependency paths, used for resolving local cache paths.
+    cache_dir : pathlib.Path
+        The root directory for caching.
+    dataset_folder : pathlib.Path
+        The specific folder for the dataset within the cache directory.
+    record : dict
+        The metadata record for the main data file, used to resolve paths.
+    s3_open_neuro : bool
+        Flag for OpenNeuro-specific path handling.
+
+    """
     filesystem = get_s3_filesystem()
     for i, dep in enumerate(bids_dependencies):
         if not s3_open_neuro:
@@ -78,8 +145,27 @@ def download_dependencies(
             _filesystem_get(filesystem=filesystem, s3path=s3path, filepath=filepath)
 
 
-def _filesystem_get(filesystem: s3fs.S3FileSystem, s3path: str, filepath: Path):
-    """Helper to download a file from S3 with a progress bar."""
+def _filesystem_get(filesystem: s3fs.S3FileSystem, s3path: str, filepath: Path) -> Path:
+    """Perform the file download using fsspec with a progress bar.
+
+    Internal helper function that wraps the ``filesystem.get`` call to include
+    a TQDM progress bar.
+
+    Parameters
+    ----------
+    filesystem : s3fs.S3FileSystem
+        The filesystem object to use for the download.
+    s3path : str
+        The full S3 URI of the source file.
+    filepath : pathlib.Path
+        The local destination path.
+
+    Returns
+    -------
+    pathlib.Path
+        The local path to the downloaded file.
+
+    """
     info = filesystem.info(s3path)
     size = info.get("size") or info.get("Size")