eegdash 0.4.0.dev173498563__py3-none-any.whl → 0.4.1.dev185__py3-none-any.whl

eegdash/hbn/windows.py

@@ -21,7 +21,25 @@ from braindecode.datasets.base import BaseConcatDataset
 
 
 def build_trial_table(events_df: pd.DataFrame) -> pd.DataFrame:
-    """One row per contrast trial with stimulus/response metrics."""
+    """Build a table of contrast trials from an events DataFrame.
+
+    This function processes a DataFrame of events (typically from a BIDS
+    `events.tsv` file) to identify contrast trials and extract relevant
+    metrics like stimulus onset, response onset, and reaction times.
+
+    Parameters
+    ----------
+    events_df : pandas.DataFrame
+        A DataFrame containing event information, with at least "onset" and
+        "value" columns.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A DataFrame where each row represents a single contrast trial, with
+        columns for onsets, reaction times, and response correctness.
+
+    """
     events_df = events_df.copy()
     events_df["onset"] = pd.to_numeric(events_df["onset"], errors="raise")
     events_df = events_df.sort_values("onset", kind="mergesort").reset_index(drop=True)
@@ -92,12 +110,13 @@ def build_trial_table(events_df: pd.DataFrame) -> pd.DataFrame:
     return pd.DataFrame(rows)
 
 
-# Aux functions to inject the annot
 def _to_float_or_none(x):
+    """Safely convert a value to float or None."""
     return None if pd.isna(x) else float(x)
 
 
 def _to_int_or_none(x):
+    """Safely convert a value to int or None."""
     if pd.isna(x):
         return None
     if isinstance(x, (bool, np.bool_)):
@@ -106,22 +125,55 @@ def _to_int_or_none(x):
         return int(x)
     try:
         return int(x)
-    except Exception:
+    except (ValueError, TypeError):
         return None
 
 
 def _to_str_or_none(x):
+    """Safely convert a value to string or None."""
     return None if (x is None or (isinstance(x, float) and np.isnan(x))) else str(x)
 
 
 def annotate_trials_with_target(
-    raw,
-    target_field="rt_from_stimulus",
-    epoch_length=2.0,
-    require_stimulus=True,
-    require_response=True,
-):
-    """Create 'contrast_trial_start' annotations with float target in extras."""
+    raw: mne.io.Raw,
+    target_field: str = "rt_from_stimulus",
+    epoch_length: float = 2.0,
+    require_stimulus: bool = True,
+    require_response: bool = True,
+) -> mne.io.Raw:
+    """Create trial annotations with a specified target value.
+
+    This function reads the BIDS events file associated with the `raw` object,
+    builds a trial table, and creates new MNE annotations for each trial.
+    The annotations are labeled "contrast_trial_start" and their `extras`
+    dictionary is populated with trial metrics, including a "target" key.
+
+    Parameters
+    ----------
+    raw : mne.io.Raw
+        The raw data object. Must have a single associated file name from
+        which the BIDS path can be derived.
+    target_field : str, default "rt_from_stimulus"
+        The column from the trial table to use as the "target" value in the
+        annotation extras.
+    epoch_length : float, default 2.0
+        The duration to set for each new annotation.
+    require_stimulus : bool, default True
+        If True, only include trials that have a recorded stimulus event.
+    require_response : bool, default True
+        If True, only include trials that have a recorded response event.
+
+    Returns
+    -------
+    mne.io.Raw
+        The `raw` object with the new annotations set.
+
+    Raises
+    ------
+    KeyError
+        If `target_field` is not a valid column in the built trial table.
+
+    """
     fnames = raw.filenames
     assert len(fnames) == 1, "Expected a single filename"
     bids_path = get_bids_path_from_fname(fnames[0])
@@ -152,7 +204,6 @@ def annotate_trials_with_target(
     extras = []
     for i, v in enumerate(targets):
         row = trials.iloc[i]
-
         extras.append(
             {
                 "target": _to_float_or_none(v),
@@ -169,14 +220,39 @@ def annotate_trials_with_target(
         onset=onsets,
         duration=durations,
         description=descs,
-        orig_time=raw.info["meas_date"],
+        orig_time=raw.info.get("meas_date"),
         extras=extras,
     )
     raw.set_annotations(new_ann, verbose=False)
     return raw
 
 
-def add_aux_anchors(raw, stim_desc="stimulus_anchor", resp_desc="response_anchor"):
+def add_aux_anchors(
+    raw: mne.io.Raw,
+    stim_desc: str = "stimulus_anchor",
+    resp_desc: str = "response_anchor",
+) -> mne.io.Raw:
+    """Add auxiliary annotations for stimulus and response onsets.
+
+    This function inspects existing "contrast_trial_start" annotations and
+    adds new, zero-duration "anchor" annotations at the precise onsets of
+    stimuli and responses for each trial.
+
+    Parameters
+    ----------
+    raw : mne.io.Raw
+        The raw data object with "contrast_trial_start" annotations.
+    stim_desc : str, default "stimulus_anchor"
+        The description for the new stimulus annotations.
+    resp_desc : str, default "response_anchor"
+        The description for the new response annotations.
+
+    Returns
+    -------
+    mne.io.Raw
+        The `raw` object with the auxiliary annotations added.
+
+    """
     ann = raw.annotations
     mask = ann.description == "contrast_trial_start"
     if not np.any(mask):
@@ -189,28 +265,24 @@ def add_aux_anchors(raw, stim_desc="stimulus_anchor", resp_desc="response_anchor
         ex = ann.extras[idx] if ann.extras is not None else {}
         t0 = float(ann.onset[idx])
 
-        stim_t = ex["stimulus_onset"]
-        resp_t = ex["response_onset"]
+        stim_t = ex.get("stimulus_onset")
+        resp_t = ex.get("response_onset")
 
         if stim_t is None or (isinstance(stim_t, float) and np.isnan(stim_t)):
-            rtt = ex["rt_from_trialstart"]
-            rts = ex["rt_from_stimulus"]
+            rtt = ex.get("rt_from_trialstart")
+            rts = ex.get("rt_from_stimulus")
             if rtt is not None and rts is not None:
                 stim_t = t0 + float(rtt) - float(rts)
 
         if resp_t is None or (isinstance(resp_t, float) and np.isnan(resp_t)):
-            rtt = ex["rt_from_trialstart"]
+            rtt = ex.get("rt_from_trialstart")
             if rtt is not None:
                 resp_t = t0 + float(rtt)
 
-        if (stim_t is not None) and not (
-            isinstance(stim_t, float) and np.isnan(stim_t)
-        ):
+        if stim_t is not None and not (isinstance(stim_t, float) and np.isnan(stim_t)):
             stim_onsets.append(float(stim_t))
             stim_extras.append(dict(ex, anchor="stimulus"))
-        if (resp_t is not None) and not (
-            isinstance(resp_t, float) and np.isnan(resp_t)
-        ):
+        if resp_t is not None and not (isinstance(resp_t, float) and np.isnan(resp_t)):
             resp_onsets.append(float(resp_t))
             resp_extras.append(dict(ex, anchor="response"))
 
@@ -220,7 +292,7 @@ def add_aux_anchors(raw, stim_desc="stimulus_anchor", resp_desc="response_anchor
             onset=new_onsets,
             duration=np.zeros_like(new_onsets, dtype=float),
             description=[stim_desc] * len(stim_onsets) + [resp_desc] * len(resp_onsets),
-            orig_time=raw.info["meas_date"],
+            orig_time=raw.info.get("meas_date"),
             extras=stim_extras + resp_extras,
         )
         raw.set_annotations(ann + aux, verbose=False)
@@ -228,10 +300,10 @@ def add_aux_anchors(raw, stim_desc="stimulus_anchor", resp_desc="response_anchor
 
 
 def add_extras_columns(
-    windows_concat_ds,
-    original_concat_ds,
-    desc="contrast_trial_start",
-    keys=(
+    windows_concat_ds: BaseConcatDataset,
+    original_concat_ds: BaseConcatDataset,
+    desc: str = "contrast_trial_start",
+    keys: tuple = (
         "target",
         "rt_from_stimulus",
         "rt_from_trialstart",
@@ -240,7 +312,31 @@ def add_extras_columns(
         "correct",
         "response_type",
     ),
-):
+) -> BaseConcatDataset:
+    """Add columns from annotation extras to a windowed dataset's metadata.
+
+    This function propagates trial-level information stored in the `extras`
+    of annotations to the `metadata` DataFrame of a `WindowsDataset`.
+
+    Parameters
+    ----------
+    windows_concat_ds : BaseConcatDataset
+        The windowed dataset whose metadata will be updated.
+    original_concat_ds : BaseConcatDataset
+        The original (non-windowed) dataset containing the raw data and
+        annotations with the `extras` to be added.
+    desc : str, default "contrast_trial_start"
+        The description of the annotations to source the extras from.
+    keys : tuple, default (...)
+        The keys to extract from each annotation's `extras` dictionary and
+        add as columns to the metadata.
+
+    Returns
+    -------
+    BaseConcatDataset
+        The `windows_concat_ds` with updated metadata.
+
+    """
     float_cols = {
         "target",
         "rt_from_stimulus",
@@ -292,7 +388,6 @@ def add_extras_columns(
             else:  # response_type
                 ser = pd.Series(vals, index=md.index, dtype="string")
 
-            # Replace the whole column to avoid dtype conflicts
             md[k] = ser
 
         win_ds.metadata = md.reset_index(drop=True)
@@ -303,7 +398,25 @@ def add_extras_columns(
     return windows_concat_ds
 
 
-def keep_only_recordings_with(desc, concat_ds):
+def keep_only_recordings_with(
+    desc: str, concat_ds: BaseConcatDataset
+) -> BaseConcatDataset:
+    """Filter a concatenated dataset to keep only recordings with a specific annotation.
+
+    Parameters
+    ----------
+    desc : str
+        The description of the annotation that must be present in a recording
+        for it to be kept.
+    concat_ds : BaseConcatDataset
+        The concatenated dataset to filter.
+
+    Returns
+    -------
+    BaseConcatDataset
+        A new concatenated dataset containing only the filtered recordings.
+
+    """
     kept = []
     for ds in concat_ds.datasets:
         if np.any(ds.raw.annotations.description == desc):

eegdash/logging.py

@@ -29,6 +29,25 @@ root_logger.setLevel(logging.INFO)
 # Now, get your package-specific logger. It will inherit the
 # configuration from the root logger we just set up.
 logger = logging.getLogger("eegdash")
+"""The primary logger for the EEGDash package.
+
+This logger is configured to use :class:`rich.logging.RichHandler` for
+formatted, colorful output in the console. It inherits its base configuration
+from the root logger, which is set to the ``INFO`` level.
+
+Examples
+--------
+Usage in other modules:
+
+.. code-block:: python
+
+    from .logging import logger
+
+    logger.info("This is an informational message.")
+    logger.warning("This is a warning.")
+    logger.error("This is an error.")
+"""
+
 
 logger.setLevel(logging.INFO)
 

eegdash/mongodb.py

@@ -4,50 +4,63 @@
 
 """MongoDB connection and operations management.
 
-This module provides thread-safe MongoDB connection management and high-level database
-operations for the EEGDash metadata database. It includes methods for finding, adding,
-and updating EEG data records with proper connection pooling and error handling.
+This module provides a thread-safe singleton manager for MongoDB connections,
+ensuring that connections to the database are handled efficiently and consistently
+across the application.
 """
 
 import threading
 
 from pymongo import MongoClient
-
-# MongoDB Operations
-# These methods provide a high-level interface to interact with the MongoDB
-# collection, allowing users to find, add, and update EEG data records.
-# - find:
-# - exist:
-# - add_request:
-# - add:
-# - update_request:
-# - remove_field:
-# - remove_field_from_db:
-# - close: Close the MongoDB connection.
-# - __del__: Destructor to close the MongoDB connection.
+from pymongo.collection import Collection
+from pymongo.database import Database
 
 
 class MongoConnectionManager:
-    """Singleton class to manage MongoDB client connections."""
+    """A thread-safe singleton to manage MongoDB client connections.
+
+    This class ensures that only one connection instance is created for each
+    unique combination of a connection string and staging flag. It provides
+    class methods to get a client and to close all active connections.
+
+    Attributes
+    ----------
+    _instances : dict
+        A dictionary to store singleton instances, mapping a
+        (connection_string, is_staging) tuple to a (client, db, collection)
+        tuple.
+    _lock : threading.Lock
+        A lock to ensure thread-safe instantiation of clients.
+
+    """
 
-    _instances = {}
+    _instances: dict[tuple[str, bool], tuple[MongoClient, Database, Collection]] = {}
     _lock = threading.Lock()
 
     @classmethod
-    def get_client(cls, connection_string: str, is_staging: bool = False):
-        """Get or create a MongoDB client for the given connection string and staging flag.
+    def get_client(
+        cls, connection_string: str, is_staging: bool = False
+    ) -> tuple[MongoClient, Database, Collection]:
+        """Get or create a MongoDB client for the given connection parameters.
+
+        This method returns a cached client if one already exists for the given
+        connection string and staging flag. Otherwise, it creates a new client,
+        connects to the appropriate database ("eegdash" or "eegdashstaging"),
+        and returns the client, database, and "records" collection.
 
         Parameters
         ----------
         connection_string : str
-            The MongoDB connection string
-        is_staging : bool
-            Whether to use staging database
+            The MongoDB connection string.
+        is_staging : bool, default False
+            If True, connect to the staging database ("eegdashstaging").
+            Otherwise, connect to the production database ("eegdash").
 
         Returns
         -------
-        tuple
-            A tuple of (client, database, collection)
+        tuple[MongoClient, Database, Collection]
+            A tuple containing the connected MongoClient instance, the Database
+            object, and the Collection object for the "records" collection.
 
         """
         # Create a unique key based on connection string and staging flag
@@ -66,8 +79,12 @@ class MongoConnectionManager:
         return cls._instances[key]
 
     @classmethod
-    def close_all(cls):
-        """Close all MongoDB client connections."""
+    def close_all(cls) -> None:
+        """Close all managed MongoDB client connections.
+
+        This method iterates through all cached client instances and closes
+        their connections. It also clears the instance cache.
+        """
         with cls._lock:
             for client, _, _ in cls._instances.values():
                 try:

eegdash/paths.py

@@ -18,12 +18,22 @@ from mne.utils import get_config as mne_get_config
 
 
 def get_default_cache_dir() -> Path:
-    """Resolve a consistent default cache directory for EEGDash.
+    """Resolve the default cache directory for EEGDash data.
+
+    The function determines the cache directory based on the following
+    priority order:
+
+     1. The path specified by the ``EEGDASH_CACHE_DIR`` environment variable.
+     2. The path specified by the ``MNE_DATA`` configuration in the MNE-Python
+         config file.
+     3. A hidden directory named ``.eegdash_cache`` in the current working
+         directory.
+
+    Returns
+    -------
+    pathlib.Path
+        The resolved, absolute path to the default cache directory.
 
-    Priority order:
-    1) Environment variable ``EEGDASH_CACHE_DIR`` if set.
-    2) MNE config ``MNE_DATA`` if set (aligns with tests and ecosystem caches).
-    3) ``.eegdash_cache`` under the current working directory.
     """
     # 1) Explicit env var wins
     env_dir = os.environ.get("EEGDASH_CACHE_DIR")

eegdash/utils.py

@@ -11,7 +11,22 @@ including MongoDB client initialization and configuration helpers.
 from mne.utils import get_config, set_config, use_log_level
 
 
-def _init_mongo_client():
+def _init_mongo_client() -> None:
+    """Initialize the default MongoDB connection URI in the MNE config.
+
+    This function checks if the ``EEGDASH_DB_URI`` is already set in the
+    MNE-Python configuration. If it is not set, this function sets it to the
+    default public EEGDash MongoDB Atlas cluster URI.
+
+    The operation is performed with MNE's logging level temporarily set to
+    "ERROR" to suppress verbose output.
+
+    Notes
+    -----
+    This is an internal helper function and is not intended for direct use
+    by end-users.
+
+    """
     with use_log_level("ERROR"):
         if get_config("EEGDASH_DB_URI") is None:
             set_config(

{eegdash-0.4.0.dev173498563.dist-info → eegdash-0.4.1.dev185.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.4.0.dev173498563
+Version: 0.4.1.dev185
 Summary: EEG data for machine learning
 Author-email: Young Truong <dt.young112@gmail.com>, Arnaud Delorme <adelorme@gmail.com>, Aviv Dotan <avivd220@gmail.com>, Oren Shriki <oren70@gmail.com>, Bruno Aristimunha <b.aristimunha@gmail.com>
 License-Expression: GPL-3.0-only
@@ -27,23 +27,17 @@ License-File: LICENSE
 Requires-Dist: braindecode>=1.0
 Requires-Dist: mne_bids>=0.17.0
 Requires-Dist: numba
-Requires-Dist: numpy
-Requires-Dist: pandas
-Requires-Dist: pybids
 Requires-Dist: pymongo
-Requires-Dist: python-dotenv
 Requires-Dist: s3fs
-Requires-Dist: scipy
 Requires-Dist: tqdm
-Requires-Dist: h5io>=0.2.4
 Requires-Dist: pymatreader
 Requires-Dist: eeglabio
 Requires-Dist: tabulate
-Requires-Dist: docstring_inheritance
 Requires-Dist: rich
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: pytest-sugar; extra == "tests"
 Requires-Dist: codecov; extra == "tests"
 Requires-Dist: pytest_cases; extra == "tests"
 Requires-Dist: pytest-benchmark; extra == "tests"
@@ -66,10 +60,15 @@ Requires-Dist: lightgbm; extra == "docs"
 Requires-Dist: plotly; extra == "docs"
 Requires-Dist: nbformat; extra == "docs"
 Requires-Dist: graphviz; extra == "docs"
+Requires-Dist: neato; extra == "docs"
+Provides-Extra: digestion
+Requires-Dist: pybids; extra == "digestion"
+Requires-Dist: python-dotenv; extra == "digestion"
 Provides-Extra: all
 Requires-Dist: eegdash[docs]; extra == "all"
 Requires-Dist: eegdash[dev]; extra == "all"
 Requires-Dist: eegdash[tests]; extra == "all"
+Requires-Dist: eegdash[digestion]; extra == "all"
 Dynamic: license-file
 
 # EEG-Dash

eegdash-0.4.1.dev185.dist-info/RECORD

@@ -0,0 +1,38 @@
+eegdash/__init__.py,sha256=GEDA8-xE1JPDzIRGN6fmVpGsBOFd2_uNrnAxp-UuN6w,704
+eegdash/api.py,sha256=saCl7_9tvblPVeTWZphw8fRXW4A2t1t2JBBp-RDvq1M,19632
+eegdash/bids_eeg_metadata.py,sha256=kEmFUe07tivkuIoC5T-YwfO4QQYJBxuc769ZBV1UCKo,16682
+eegdash/const.py,sha256=9WMetN7YMQJbkN2PhzItxtVRZ4VBXLP82vFu9pY6xok,9066
+eegdash/downloader.py,sha256=Z-9EEJildqJxIihwdtXc_h9kzCkuF9LWIwQEfyG9Huw,6030
+eegdash/logging.py,sha256=OQ4jMtwv1h-gzjxmr3PCpcsKi5-3Nhd3r9PJ4UN7oQI,1467
+eegdash/mongodb.py,sha256=9FJDeEebOD5RzNYfAf1lhr0R-pECAlnug6Sjhd9_oUw,3469
+eegdash/paths.py,sha256=iXzBUindjIwgkf2k0Phm2InChOfPZNGilQmGwJ8zNO0,1507
+eegdash/utils.py,sha256=u_fQ8DiA1b7dVLzwzZBhm8H-LUk6dga54WyqbbqYEJ4,1282
+eegdash/dataset/__init__.py,sha256=EXmCtcIWz2_iq7-04AzOPmOxfv1hvUGnrSRgu_Je800,975
+eegdash/dataset/base.py,sha256=dHCiUtoZddflLpUD-q2yIDImMfcIVZmTuvRRJflVS8s,11718
+eegdash/dataset/bids_dataset.py,sha256=577D_kqig4xmW_fYz1VbaUbGWPquL33eT97ge_CbXpQ,14919
+eegdash/dataset/dataset.py,sha256=IDAGg5qDeh1R48nFMiyG6_9CxenS2KK56VeuvM_w5tM,27593
+eegdash/dataset/dataset_summary.csv,sha256=YJX-BitOyo-5nsHBd3ECIY1u7lFBjMQAFfCUPLYEgpo,25289
+eegdash/dataset/registry.py,sha256=5TOCWalA0RV7omRoYS0OzdcSaOTvXvqos74_Vj2jv0M,9127
+eegdash/features/__init__.py,sha256=BXNhjvL4_SSFAY1lcP9nyGpkbJNtoOMH4AHlF6OyABo,4078
+eegdash/features/datasets.py,sha256=79Xey6SouPHMKybF78madVl5i7P0f03jnostBV6Dr7M,24880
+eegdash/features/decorators.py,sha256=Gvk-5VtqatpH7BBVVV3pcz1KJKygd-ZU8mniR_Tpvlw,4052
+eegdash/features/extractors.py,sha256=R4csU3jj95xndtWI1VuMKoKi26xprzmuOp9wcy9iVzI,11937
+eegdash/features/inspect.py,sha256=GpNV4708XPn4LXl5BXy8e0GNr_DSrojxjAT9c7POxqk,4373
+eegdash/features/serialization.py,sha256=f981K8DcfaLZ0q98IBrXeAbMHnPmKBbp7cFiXZnjezw,4194
+eegdash/features/utils.py,sha256=SuvPE6N_ccm-Ar4g-1dgVj1qaW2bV9hNQivtz946hlY,6487
+eegdash/features/feature_bank/__init__.py,sha256=YsMXLC1FEtHL3IEw9pYw1fc5IY0x_hr2qWQowI5gZj8,2991
+eegdash/features/feature_bank/complexity.py,sha256=eOLN0X_xaS15ZpLPDQcychuwjL459-FqZKYfOG51z-g,3366
+eegdash/features/feature_bank/connectivity.py,sha256=bQ6KlxWm5GNpCS9ypLqBUr2L171Yq7wpBQT2tRQKTZ4,2159
+eegdash/features/feature_bank/csp.py,sha256=jKPrmqBj7FliybNbg035cVZddvVSkhk9OazcscDpipU,3303
+eegdash/features/feature_bank/dimensionality.py,sha256=Pit3YNxv64-qHUyz_5c3nBo4sFD5AnCE5mTwgnzSndc,3980
+eegdash/features/feature_bank/signal.py,sha256=iSMrgnZLKNn1qNdBPheEoE_UcJPPLAOv3qDTaRI1BcE,3431
+eegdash/features/feature_bank/spectral.py,sha256=bNB7skusePs1gX7NOU6yRlw_Gr4UOCkO_ylkCgybzug,3319
+eegdash/features/feature_bank/utils.py,sha256=zCdkfDMLWJhPjBqb5Xz0jLKg8gm3qQDY1G1rZTLuCaM,1354
+eegdash/hbn/__init__.py,sha256=hsI5pmIuYDzr--aE5UiToO-P9XL5fVRKahZzdsAodro,794
+eegdash/hbn/preprocessing.py,sha256=xp0HBz8WGhLI5c2Zkk4QiVUzGoIZep8YypnHNZsUJ4o,3800
+eegdash/hbn/windows.py,sha256=Z_fhG3kaHd5MAPg60FwFnxMJay8EzacXytUaCsOENGc,14408
+eegdash-0.4.1.dev185.dist-info/licenses/LICENSE,sha256=asisR-xupy_NrQBFXnx6yqXeZcYWLvbAaiETl25iXT0,931
+eegdash-0.4.1.dev185.dist-info/METADATA,sha256=kprps0odUjO5HR9uFhU6L1GCUFf69AqfX91lSh5ojkM,6880
+eegdash-0.4.1.dev185.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+eegdash-0.4.1.dev185.dist-info/top_level.txt,sha256=zavO69HQ6MyZM0aQMR2zUS6TAFc7bnN5GEpDpOpFZzU,8
+eegdash-0.4.1.dev185.dist-info/RECORD,,