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

eegdash/bids_eeg_metadata.py

@@ -1,28 +1,62 @@
-import logging
+# Authors: The EEGDash contributors.
+# License: GNU General Public License
+# Copyright the EEGDash contributors.
+
+"""BIDS metadata processing and query building utilities.
+
+This module provides functions for processing BIDS-formatted EEG metadata, building database
+queries from user parameters, and enriching metadata records with participant information.
+It handles the translation between user-friendly query parameters and MongoDB query syntax.
+"""
+
 import re
 from pathlib import Path
 from typing import Any
 
+import pandas as pd
+from mne_bids import BIDSPath
+
 from .const import ALLOWED_QUERY_FIELDS
 from .const import config as data_config
-
-logger = logging.getLogger("eegdash")
+from .logging import logger
 
 __all__ = [
     "build_query_from_kwargs",
     "load_eeg_attrs_from_bids_file",
     "merge_participants_fields",
     "normalize_key",
+    "participants_row_for_subject",
+    "participants_extras_from_tsv",
+    "attach_participants_extras",
+    "enrich_from_participants",
 ]
 
 
 def build_query_from_kwargs(**kwargs) -> dict[str, Any]:
-    """Build and validate a MongoDB query from user-friendly keyword arguments.
+    """Build and validate a MongoDB query from keyword arguments.
+
+    This function converts user-friendly keyword arguments into a valid
+    MongoDB query dictionary. It handles scalar values as exact matches and
+    list-like values as ``$in`` queries. It also performs validation to
+    reject unsupported fields and empty values.
+
+    Parameters
+    ----------
+    **kwargs
+        Keyword arguments representing query filters. Allowed keys are defined
+        in ``eegdash.const.ALLOWED_QUERY_FIELDS``.
+
+    Returns
+    -------
+    dict
+        A MongoDB query dictionary.
+
+    Raises
+    ------
+    ValueError
+        If an unsupported query field is provided, or if a value is None or
+        an empty string/list.
 
-    Improvements:
-    - Reject None values and empty/whitespace-only strings
-    - For list/tuple/set values: strip strings, drop None/empties, deduplicate, and use `$in`
-    - Preserve scalars as exact matches
     """
     # 1. Validate that all provided keys are allowed for querying
     unknown_fields = set(kwargs.keys()) - ALLOWED_QUERY_FIELDS
@@ -72,47 +106,30 @@ def build_query_from_kwargs(**kwargs) -> dict[str, Any]:
     return query
 
 
-def _get_raw_extensions(bids_file: str, bids_dataset) -> list[str]:
-    """Helper to find paths to additional "sidecar" files that may be associated
-    with a given main data file in a BIDS dataset; paths are returned as relative to
-    the parent dataset path.
-
-    For example, if the input file is a .set file, this will return the relative path
-    to a corresponding .fdt file (if any).
-    """
-    bids_file = Path(bids_file)
-    extensions = {
-        ".set": [".set", ".fdt"],  # eeglab
-        ".edf": [".edf"],  # european
-        ".vhdr": [".eeg", ".vhdr", ".vmrk", ".dat", ".raw"],  # brainvision
-        ".bdf": [".bdf"],  # biosemi
-    }
-    return [
-        str(bids_dataset._get_relative_bidspath(bids_file.with_suffix(suffix)))
-        for suffix in extensions[bids_file.suffix]
-        if bids_file.with_suffix(suffix).exists()
-    ]
-
-
 def load_eeg_attrs_from_bids_file(bids_dataset, bids_file: str) -> dict[str, Any]:
-    """Build the metadata record for a given BIDS file (single recording) in a BIDS dataset.
+    """Build a metadata record for a BIDS file.
 
-    Attributes are at least the ones defined in data_config attributes (set to None if missing),
-    but are typically a superset, and include, among others, the paths to relevant
-    meta-data files needed to load and interpret the file in question.
+    Extracts metadata attributes from a single BIDS EEG file within a given
+    BIDS dataset. The extracted attributes include BIDS entities, file paths,
+    and technical metadata required for database indexing.
 
     Parameters
     ----------
     bids_dataset : EEGBIDSDataset
         The BIDS dataset object containing the file.
     bids_file : str
-        The path to the BIDS file within the dataset.
+        The path to the BIDS file to process.
 
     Returns
     -------
-    dict:
-        A dictionary representing the metadata record for the given file. This is the
-        same format as the records stored in the database.
+    dict
+        A dictionary of metadata attributes for the file, suitable for
+        insertion into the database.
+
+    Raises
+    ------
+    ValueError
+        If ``bids_file`` is not found in the ``bids_dataset``.
 
     """
     if bids_file not in bids_dataset.files:
@@ -140,7 +157,7 @@ def load_eeg_attrs_from_bids_file(bids_dataset, bids_file: str) -> dict[str, Any
         eeg_json = None
 
     bids_dependencies_files = data_config["bids_dependencies_files"]
-    bidsdependencies = []
+    bidsdependencies: list[str] = []
     for extension in bids_dependencies_files:
         try:
             dep_path = bids_dataset.get_bids_metadata_files(bids_file, extension)
@@ -151,7 +168,26 @@ def load_eeg_attrs_from_bids_file(bids_dataset, bids_file: str) -> dict[str, Any
         except Exception:
             pass
 
-    bidsdependencies.extend(_get_raw_extensions(bids_file, bids_dataset))
+    bids_path = BIDSPath(
+        subject=bids_dataset.get_bids_file_attribute("subject", bids_file),
+        session=bids_dataset.get_bids_file_attribute("session", bids_file),
+        task=bids_dataset.get_bids_file_attribute("task", bids_file),
+        run=bids_dataset.get_bids_file_attribute("run", bids_file),
+        root=bids_dataset.bidsdir,
+        datatype=bids_dataset.get_bids_file_attribute("modality", bids_file),
+        suffix="eeg",
+        extension=Path(bids_file).suffix,
+        check=False,
+    )
+
+    sidecars_map = {
+        ".set": [".fdt"],
+        ".vhdr": [".eeg", ".vmrk", ".dat", ".raw"],
+    }
+    for ext in sidecars_map.get(bids_path.extension, []):
+        sidecar = bids_path.find_matching_sidecar(extension=ext, on_error="ignore")
+        if sidecar is not None:
+            bidsdependencies.append(str(bids_dataset._get_relative_bidspath(sidecar)))
 
     # Define field extraction functions with error handling
     field_extractors = {
@@ -185,11 +221,23 @@ def load_eeg_attrs_from_bids_file(bids_dataset, bids_file: str) -> dict[str, Any
 
 
 def normalize_key(key: str) -> str:
-    """Normalize a metadata key for robust matching.
+    """Normalize a string key for robust matching.
+
+    Converts the key to lowercase, replaces non-alphanumeric characters with
+    underscores, and removes leading/trailing underscores. This allows for
+    tolerant matching of keys that may have different capitalization or
+    separators (e.g., "p-factor" becomes "p_factor").
+
+    Parameters
+    ----------
+    key : str
+        The key to normalize.
+
+    Returns
+    -------
+    str
+        The normalized key.
 
-    Lowercase and replace non-alphanumeric characters with underscores, then strip
-    leading/trailing underscores. This allows tolerant matching such as
-    "p-factor" ≈ "p_factor" ≈ "P Factor".
     """
     return re.sub(r"[^a-z0-9]+", "_", str(key).lower()).strip("_")
 
@@ -199,27 +247,27 @@ def merge_participants_fields(
     participants_row: dict[str, Any] | None,
     description_fields: list[str] | None = None,
 ) -> dict[str, Any]:
-    """Merge participants.tsv fields into a dataset description dictionary.
+    """Merge fields from a participants.tsv row into a description dict.
 
-    - Preserves existing entries in ``description`` (no overwrites).
-    - Fills requested ``description_fields`` first, preserving their original names.
-    - Adds all remaining participants columns generically using normalized keys
-      unless a matching requested field already captured them.
+    Enriches a description dictionary with data from a subject's row in
+    ``participants.tsv``. It avoids overwriting existing keys in the
+    description.
 
     Parameters
     ----------
     description : dict
-        Current description to be enriched in-place and returned.
-    participants_row : dict | None
-        A mapping of participants.tsv columns for the current subject.
-    description_fields : list[str] | None
-        Optional list of requested description fields. When provided, matching is
-        performed by normalized names; the original requested field names are kept.
+        The description dictionary to enrich.
+    participants_row : dict or None
+        A dictionary representing a row from ``participants.tsv``. If None,
+        the original description is returned unchanged.
+    description_fields : list of str, optional
+        A list of specific fields to include in the description. Matching is
+        done using normalized keys.
 
     Returns
     -------
     dict
-        The enriched description (same object as input for convenience).
+        The enriched description dictionary.
 
     """
     if not isinstance(description, dict) or not isinstance(participants_row, dict):
@@ -252,3 +300,196 @@ def merge_participants_fields(
         if norm_key not in description:
             description[norm_key] = part_value
     return description
+
+
+def participants_row_for_subject(
+    bids_root: str | Path,
+    subject: str,
+    id_columns: tuple[str, ...] = ("participant_id", "participant", "subject"),
+) -> pd.Series | None:
+    """Load participants.tsv and return the row for a specific subject.
+
+    Searches for a subject's data in the ``participants.tsv`` file within a
+    BIDS dataset. It can identify the subject with or without the "sub-"
+    prefix.
+
+    Parameters
+    ----------
+    bids_root : str or Path
+        The root directory of the BIDS dataset.
+    subject : str
+        The subject identifier (e.g., "01" or "sub-01").
+    id_columns : tuple of str, default ("participant_id", "participant", "subject")
+        A tuple of column names to search for the subject identifier.
+
+    Returns
+    -------
+    pandas.Series or None
+        A pandas Series containing the subject's data if found, otherwise None.
+
+    """
+    try:
+        participants_tsv = Path(bids_root) / "participants.tsv"
+        if not participants_tsv.exists():
+            return None
+
+        df = pd.read_csv(
+            participants_tsv, sep="\t", dtype="string", keep_default_na=False
+        )
+        if df.empty:
+            return None
+
+        candidates = {str(subject), f"sub-{subject}"}
+        present_cols = [c for c in id_columns if c in df.columns]
+        if not present_cols:
+            return None
+
+        mask = pd.Series(False, index=df.index)
+        for col in present_cols:
+            mask |= df[col].isin(candidates)
+        match = df.loc[mask]
+        if match.empty:
+            return None
+        return match.iloc[0]
+    except Exception:
+        return None
+
+
+def participants_extras_from_tsv(
+    bids_root: str | Path,
+    subject: str,
+    *,
+    id_columns: tuple[str, ...] = ("participant_id", "participant", "subject"),
+    na_like: tuple[str, ...] = ("", "n/a", "na", "nan", "unknown", "none"),
+) -> dict[str, Any]:
+    """Extract additional participant information from participants.tsv.
+
+    Retrieves all non-identifier and non-empty fields for a subject from
+    the ``participants.tsv`` file.
+
+    Parameters
+    ----------
+    bids_root : str or Path
+        The root directory of the BIDS dataset.
+    subject : str
+        The subject identifier.
+    id_columns : tuple of str, default ("participant_id", "participant", "subject")
+        Column names to be treated as identifiers and excluded from the
+        output.
+    na_like : tuple of str, default ("", "n/a", "na", "nan", "unknown", "none")
+        Values to be considered as "Not Available" and excluded.
+
+    Returns
+    -------
+    dict
+        A dictionary of extra participant information.
+
+    """
+    row = participants_row_for_subject(bids_root, subject, id_columns=id_columns)
+    if row is None:
+        return {}
+
+    # Drop identifier columns and clean values
+    extras = row.drop(labels=[c for c in id_columns if c in row.index], errors="ignore")
+    s = extras.astype("string").str.strip()
+    valid = ~s.isna() & ~s.str.lower().isin(na_like)
+    return s[valid].to_dict()
+
+
+def attach_participants_extras(
+    raw: Any,
+    description: Any,
+    extras: dict[str, Any],
+) -> None:
+    """Attach extra participant data to a raw object and its description.
+
+    Updates the ``raw.info['subject_info']`` and the description object
+    (dict or pandas Series) with extra data from ``participants.tsv``.
+    It does not overwrite existing keys.
+
+    Parameters
+    ----------
+    raw : mne.io.Raw
+        The MNE Raw object to be updated.
+    description : dict or pandas.Series
+        The description object to be updated.
+    extras : dict
+        A dictionary of extra participant information to attach.
+
+    """
+    if not extras:
+        return
+
+    # Raw.info enrichment
+    try:
+        subject_info = raw.info.get("subject_info") or {}
+        if not isinstance(subject_info, dict):
+            subject_info = {}
+        pe = subject_info.get("participants_extras") or {}
+        if not isinstance(pe, dict):
+            pe = {}
+        for k, v in extras.items():
+            pe.setdefault(k, v)
+        subject_info["participants_extras"] = pe
+        raw.info["subject_info"] = subject_info
+    except Exception:
+        pass
+
+    # Description enrichment
+    try:
+        import pandas as _pd  # local import to avoid hard dependency at import time
+
+        if isinstance(description, dict):
+            for k, v in extras.items():
+                description.setdefault(k, v)
+        elif isinstance(description, _pd.Series):
+            missing = [k for k in extras.keys() if k not in description.index]
+            if missing:
+                description.loc[missing] = [extras[m] for m in missing]
+    except Exception:
+        pass
+
+
+def enrich_from_participants(
+    bids_root: str | Path,
+    bidspath: BIDSPath,
+    raw: Any,
+    description: Any,
+) -> dict[str, Any]:
+    """Read participants.tsv and attach extra info for the subject.
+
+    This is a convenience function that finds the subject from the
+    ``bidspath``, retrieves extra information from ``participants.tsv``,
+    and attaches it to the raw object and its description.
+
+    Parameters
+    ----------
+    bids_root : str or Path
+        The root directory of the BIDS dataset.
+    bidspath : mne_bids.BIDSPath
+        The BIDSPath object for the current data file.
+    raw : mne.io.Raw
+        The MNE Raw object to be updated.
+    description : dict or pandas.Series
+        The description object to be updated.
+
+    Returns
+    -------
+    dict
+        The dictionary of extras that were attached.
+
+    """
+    subject = getattr(bidspath, "subject", None)
+    if not subject:
+        return {}
+    extras = participants_extras_from_tsv(bids_root, subject)
+    attach_participants_extras(raw, description, extras)
+    return extras
+
+
+__all__ = [
+    "participants_row_for_subject",
+    "participants_extras_from_tsv",
+    "attach_participants_extras",
+    "enrich_from_participants",
+]

eegdash/const.py

@@ -1,3 +1,21 @@
+# Authors: The EEGDash contributors.
+# License: GNU General Public License
+# Copyright the EEGDash contributors.
+
+"""Configuration constants and mappings for EEGDash.
+
+This module contains global configuration settings, allowed query fields, and mapping
+constants used throughout the EEGDash package. It defines the interface between EEGDash
+releases and OpenNeuro dataset identifiers, as well as validation rules for database queries.
+"""
+
+__all__ = [
+    "config",
+    "ALLOWED_QUERY_FIELDS",
+    "RELEASE_TO_OPENNEURO_DATASET_MAP",
+    "SUBJECT_MINI_RELEASE_MAP",
+]
+
 ALLOWED_QUERY_FIELDS = {
     "data_name",
     "dataset",
@@ -10,6 +28,8 @@ ALLOWED_QUERY_FIELDS = {
     "nchans",
     "ntimes",
 }
+"""set: A set of field names that are permitted in database queries constructed
+via :func:`~eegdash.api.EEGDash.find` with keyword arguments."""
 
 RELEASE_TO_OPENNEURO_DATASET_MAP = {
     "R11": "ds005516",
@@ -24,6 +44,8 @@ RELEASE_TO_OPENNEURO_DATASET_MAP = {
     "R2": "ds005506",
     "R1": "ds005505",
 }
+"""dict: A mapping from Healthy Brain Network (HBN) release identifiers (e.g., "R11")
+to their corresponding OpenNeuro dataset identifiers (e.g., "ds005516")."""
 
 SUBJECT_MINI_RELEASE_MAP = {
     "R11": [
@@ -269,6 +291,9 @@ SUBJECT_MINI_RELEASE_MAP = {
         "NDARFW972KFQ",
     ],
 }
+"""dict: A mapping from HBN release identifiers to a list of subject IDs.
+This is used to select a small, representative subset of subjects for creating
+"mini" datasets for testing and demonstration purposes."""
 
 config = {
     "required_fields": ["data_name"],
@@ -304,3 +329,21 @@ config = {
     ],
     "accepted_query_fields": ["data_name", "dataset"],
 }
+"""dict: A global configuration dictionary for the EEGDash package.
+
+Keys
+----
+required_fields : list
+    Fields that must be present in every database record.
+attributes : dict
+    A schema defining the expected primary attributes and their types for a
+    database record.
+description_fields : list
+    A list of fields considered to be descriptive metadata for a recording,
+    which can be used for filtering and display.
+bids_dependencies_files : list
+    A list of BIDS metadata filenames that are relevant for interpreting an
+    EEG recording.
+accepted_query_fields : list
+    Fields that are accepted for lightweight existence checks in the database.
+"""