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

eegdash/data_utils.py

@@ -20,13 +20,10 @@ from typing import Any
 
 import mne
 import mne_bids
-import numpy as np
 import pandas as pd
-from bids import BIDSLayout
-from joblib import Parallel, delayed
 from mne._fiff.utils import _read_segments_file
 from mne.io import BaseRaw
-from mne_bids import BIDSPath
+from mne_bids import BIDSPath, find_matching_paths
 
 from braindecode.datasets import BaseDataset
 
@@ -37,10 +34,26 @@ from .paths import get_default_cache_dir
 
 
 class EEGDashBaseDataset(BaseDataset):
-    """A single EEG recording hosted on AWS S3 and cached locally upon first access.
+    """A single EEG recording dataset.
+
+    Represents a single EEG recording, typically hosted on a remote server (like AWS S3)
+    and cached locally upon first access. This class is a subclass of
+    :class:`braindecode.datasets.BaseDataset` and can be used with braindecode's
+    preprocessing and training pipelines.
+
+    Parameters
+    ----------
+    record : dict
+        A fully resolved metadata record for the data to load.
+    cache_dir : str
+        The local directory where the data will be cached.
+    s3_bucket : str, optional
+        The S3 bucket to download data from. If not provided, defaults to the
+        OpenNeuro bucket.
+    **kwargs
+        Additional keyword arguments passed to the
+        :class:`braindecode.datasets.BaseDataset` constructor.
 
-    This is a subclass of braindecode's BaseDataset, which can consequently be used in
-    conjunction with the preprocessing and training pipelines of braindecode.
     """
 
     _AWS_BUCKET = "s3://openneuro.org"
@@ -52,20 +65,6 @@ class EEGDashBaseDataset(BaseDataset):
         s3_bucket: str | None = None,
         **kwargs,
     ):
-        """Create a new EEGDashBaseDataset instance. Users do not usually need to call this
-        directly -- instead use the EEGDashDataset class to load a collection of these
-        recordings from a local BIDS folder or using a database query.
-
-        Parameters
-        ----------
-        record : dict
-            A fully resolved metadata record for the data to load.
-        cache_dir : str
-            A local directory where the data will be cached.
-        kwargs : dict
-            Additional keyword arguments to pass to the BaseDataset constructor.
-
-        """
         super().__init__(None, **kwargs)
         self.record = record
         self.cache_dir = Path(cache_dir)
@@ -121,14 +120,12 @@ class EEGDashBaseDataset(BaseDataset):
         self._raw = None
 
     def _get_raw_bids_args(self) -> dict[str, Any]:
-        """Helper to restrict the metadata record to the fields needed to locate a BIDS
-        recording.
-        """
+        """Extract BIDS-related arguments from the metadata record."""
         desired_fields = ["subject", "session", "task", "run"]
         return {k: self.record[k] for k in desired_fields if self.record[k]}
 
     def _ensure_raw(self) -> None:
-        """Download the S3 file and BIDS dependencies if not already cached."""
+        """Ensure the raw data file and its dependencies are cached locally."""
         # TO-DO: remove this once is fixed on the our side
         # for the competition
         if not self.s3_open_neuro:
@@ -190,42 +187,53 @@ class EEGDashBaseDataset(BaseDataset):
         return len(self._raw)
 
     @property
-    def raw(self):
-        """Return the MNE Raw object for this recording. This will perform the actual
-        retrieval if not yet done so.
+    def raw(self) -> BaseRaw:
+        """The MNE Raw object for this recording.
+
+        Accessing this property triggers the download and caching of the data
+        if it has not been accessed before.
+
+        Returns
+        -------
+        mne.io.BaseRaw
+            The loaded MNE Raw object.
+
         """
         if self._raw is None:
             self._ensure_raw()
         return self._raw
 
     @raw.setter
-    def raw(self, raw):
+    def raw(self, raw: BaseRaw):
         self._raw = raw
 
 
 class EEGDashBaseRaw(BaseRaw):
-    """Wrapper around the MNE BaseRaw class that automatically fetches the data from S3
-    (when _read_segment is called) and caches it locally. Currently for internal use.
+    """MNE BaseRaw wrapper for automatic S3 data fetching.
+
+    This class extends :class:`mne.io.BaseRaw` to automatically fetch data
+    from an S3 bucket and cache it locally when data is first accessed.
+    It is intended for internal use within the EEGDash ecosystem.
 
     Parameters
     ----------
-    input_fname : path-like
-        Path to the S3 file
+    input_fname : str
+        The path to the file on the S3 bucket (relative to the bucket root).
     metadata : dict
-        The metadata record for the recording (e.g., from the database).
-    preload : bool
-        Whether to pre-loaded the data before the first access.
-    cache_dir : str
-        Local path under which the data will be cached.
-    bids_dependencies : list
-        List of additional BIDS metadata files that should be downloaded and cached
-        alongside the main recording file.
-    verbose : str | int | None
-        Optionally the verbosity level for MNE logging (see MNE documentation for possible values).
+        The metadata record for the recording, containing information like
+        sampling frequency, channel names, etc.
+    preload : bool, default False
+        If True, preload the data into memory.
+    cache_dir : str, optional
+        Local directory for caching data. If None, a default directory is used.
+    bids_dependencies : list of str, default []
+        A list of BIDS metadata files to download alongside the main recording.
+    verbose : str, int, or None, default None
+        The MNE verbosity level.
 
     See Also
     --------
-    mne.io.Raw : Documentation of attributes and methods.
+    mne.io.Raw : The base class for Raw objects in MNE.
 
     """
 
@@ -241,7 +249,6 @@ class EEGDashBaseRaw(BaseRaw):
         bids_dependencies: list[str] = [],
         verbose: Any = None,
     ):
-        """Get to work with S3 endpoint first, no caching"""
         # Create a simple RawArray
         sfreq = metadata["sfreq"]  # Sampling frequency
         n_times = metadata["n_times"]
@@ -277,6 +284,7 @@ class EEGDashBaseRaw(BaseRaw):
     def _read_segment(
         self, start=0, stop=None, sel=None, data_buffer=None, *, verbose=None
     ):
+        """Read a segment of data, downloading if necessary."""
         if not os.path.exists(self.filecache):  # not preload
             if self.bids_dependencies:  # this is use only to sidecars for now
                 downloader.download_dependencies(
@@ -297,22 +305,23 @@ class EEGDashBaseRaw(BaseRaw):
         return super()._read_segment(start, stop, sel, data_buffer, verbose=verbose)
 
     def _read_segment_file(self, data, idx, fi, start, stop, cals, mult):
-        """Read a chunk of data from the file."""
+        """Read a chunk of data from a local file."""
         _read_segments_file(self, data, idx, fi, start, stop, cals, mult, dtype="<f4")
 
 
 class EEGBIDSDataset:
-    """A one-stop shop interface to a local BIDS dataset containing EEG recordings.
+    """An interface to a local BIDS dataset containing EEG recordings.
 
-    This is mainly tailored to the needs of EEGDash application and is used to centralize
-    interactions with the BIDS dataset, such as parsing the metadata.
+    This class centralizes interactions with a BIDS dataset on the local
+    filesystem, providing methods to parse metadata, find files, and
+    retrieve BIDS-related information.
 
     Parameters
     ----------
-    data_dir : str | Path
+    data_dir : str or Path
         The path to the local BIDS dataset directory.
     dataset : str
-        A name for the dataset.
+        A name for the dataset (e.g., "ds002718").
 
     """
 
@@ -338,8 +347,11 @@ class EEGBIDSDataset:
     ):
         if data_dir is None or not os.path.exists(data_dir):
             raise ValueError("data_dir must be specified and must exist")
+
         self.bidsdir = Path(data_dir)
         self.dataset = dataset
+        self.data_dir = data_dir
+
         # Accept exact dataset folder or a variant with informative suffixes
         # (e.g., dsXXXXX-bdf, dsXXXXX-bdf-mini) to avoid collisions.
         dir_name = self.bidsdir.name
@@ -347,331 +359,376 @@ class EEGBIDSDataset:
             raise AssertionError(
                 f"BIDS directory '{dir_name}' does not correspond to dataset '{self.dataset}'"
             )
-        self.layout = BIDSLayout(data_dir)
+
+        # Initialize BIDS paths using fast mne_bids approach instead of pybids
+        self._init_bids_paths()
 
         # get all recording files in the bids directory
-        self.files = self._get_recordings(self.layout)
         assert len(self.files) > 0, ValueError(
             "Unable to construct EEG dataset. No EEG recordings found."
         )
         assert self.check_eeg_dataset(), ValueError("Dataset is not an EEG dataset.")
 
     def check_eeg_dataset(self) -> bool:
-        """Check if the dataset is EEG."""
+        """Check if the BIDS dataset contains EEG data.
+
+        Returns
+        -------
+        bool
+            True if the dataset's modality is EEG, False otherwise.
+
+        """
         return self.get_bids_file_attribute("modality", self.files[0]).lower() == "eeg"
 
-    def _get_recordings(self, layout: BIDSLayout) -> list[str]:
-        """Get a list of all EEG recording files in the BIDS layout."""
-        files = []
-        for ext, exts in self.RAW_EXTENSIONS.items():
-            files = layout.get(extension=ext, return_type="filename")
-            if files:
+    def _init_bids_paths(self) -> None:
+        """Initialize BIDS file paths using mne_bids for fast discovery.
+
+        Uses mne_bids.find_matching_paths() for efficient pattern-based file
+        discovery instead of heavy pybids BIDSLayout indexing.
+        """
+        # Initialize cache for BIDSPath objects
+        self._bids_path_cache = {}
+
+        # Find all EEG recordings using pattern matching (fast!)
+        self.files = []
+        for ext in self.RAW_EXTENSIONS.keys():
+            # find_matching_paths returns BIDSPath objects
+            paths = find_matching_paths(self.bidsdir, datatypes="eeg", extensions=ext)
+            if paths:
+                # Convert BIDSPath objects to filename strings
+                self.files = [str(p.fpath) for p in paths]
                 break
-        return files
 
-    def _get_relative_bidspath(self, filename: str) -> str:
-        """Make the given file path relative to the BIDS directory."""
-        bids_parent_dir = self.bidsdir.parent.absolute()
-        return str(Path(filename).relative_to(bids_parent_dir))
+    def _get_bids_path_from_file(self, data_filepath: str):
+        """Get a BIDSPath object for a data file with caching.
 
-    def _get_property_from_filename(self, property: str, filename: str) -> str:
-        """Parse a property out of a BIDS-compliant filename. Returns an empty string
-        if not found.
-        """
-        import platform
+        Parameters
+        ----------
+        data_filepath : str
+            The path to the data file.
 
-        if platform.system() == "Windows":
-            lookup = re.search(rf"{property}-(.*?)[_\\]", filename)
-        else:
-            lookup = re.search(rf"{property}-(.*?)[_\/]", filename)
-        return lookup.group(1) if lookup else ""
+        Returns
+        -------
+        BIDSPath
+            The BIDSPath object for the file.
 
-    def _merge_json_inheritance(self, json_files: list[str | Path]) -> dict:
-        """Internal helper to merge list of json files found by get_bids_file_inheritance,
-        expecting the order (from left to right) is from lowest
-        level to highest level, and return a merged dictionary
         """
-        json_files.reverse()
-        json_dict = {}
-        for f in json_files:
-            json_dict.update(json.load(open(f)))  # FIXME: should close file
-        return json_dict
+        if data_filepath not in self._bids_path_cache:
+            # Parse the filename to extract BIDS entities
+            filepath = Path(data_filepath)
+            filename = filepath.name
+
+            # Extract entities from filename using BIDS pattern
+            # Expected format: sub-<label>[_ses-<label>][_task-<label>][_run-<label>]_eeg.<ext>
+            subject = re.search(r"sub-([^_]*)", filename)
+            session = re.search(r"ses-([^_]*)", filename)
+            task = re.search(r"task-([^_]*)", filename)
+            run = re.search(r"run-([^_]*)", filename)
+
+            bids_path = BIDSPath(
+                subject=subject.group(1) if subject else None,
+                session=session.group(1) if session else None,
+                task=task.group(1) if task else None,
+                run=int(run.group(1)) if run else None,
+                datatype="eeg",
+                extension=filepath.suffix,
+                root=self.bidsdir,
+            )
+            self._bids_path_cache[data_filepath] = bids_path
 
-    def _get_bids_file_inheritance(
-        self, path: str | Path, basename: str, extension: str
-    ) -> list[Path]:
-        """Get all file paths that apply to the basename file in the specified directory
-        and that end with the specified suffix, recursively searching parent directories
-        (following the BIDS inheritance principle in the order of lowest level first).
+        return self._bids_path_cache[data_filepath]
+
+    def _get_json_with_inheritance(
+        self, data_filepath: str, json_filename: str
+    ) -> dict:
+        """Get JSON metadata with BIDS inheritance handling.
+
+        Walks up the directory tree to find and merge JSON files following
+        BIDS inheritance principles.
 
         Parameters
         ----------
-        path : str | Path
-            The directory path to search for files.
-        basename : str
-            BIDS file basename without _eeg.set extension for example
-        extension : str
-            Only consider files that end with the specified suffix; e.g. channels.tsv
+        data_filepath : str
+            The path to the data file.
+        json_filename : str
+            The name of the JSON file to find (e.g., "eeg.json").
 
         Returns
         -------
-        list[Path]
-            A list of file paths that match the given basename and extension.
+        dict
+            The merged JSON metadata.
 
         """
+        json_dict = {}
+        current_dir = Path(data_filepath).parent
+        root_dir = self.bidsdir
+
+        # Walk up from file directory to root, collecting JSON files
+        while current_dir >= root_dir:
+            json_path = current_dir / json_filename
+            if json_path.exists():
+                with open(json_path) as f:
+                    json_dict.update(json.load(f))
+
+            # Stop at BIDS root (contains dataset_description.json)
+            if (current_dir / "dataset_description.json").exists():
+                break
+
+            current_dir = current_dir.parent
+
+        return json_dict
+
+    def _merge_json_inheritance(self, json_files: list[str | Path]) -> dict:
+        """Merge a list of JSON files according to BIDS inheritance."""
+        json_files.reverse()
+        json_dict = {}
+        for f in json_files:
+            with open(f) as fp:
+                json_dict.update(json.load(fp))
+        return json_dict
+
+    def _get_bids_file_inheritance(
+        self, path: str | Path, basename: str, extension: str
+    ) -> list[Path]:
+        """Find all applicable metadata files using BIDS inheritance."""
         top_level_files = ["README", "dataset_description.json", "participants.tsv"]
         bids_files = []
 
-        # check if path is str object
         if isinstance(path, str):
             path = Path(path)
-        if not path.exists:
-            raise ValueError("path {path} does not exist")
+        if not path.exists():
+            raise ValueError(f"path {path} does not exist")
 
-        # check if file is in current path
         for file in os.listdir(path):
-            # target_file = path / f"{cur_file_basename}_{extension}"
-            if os.path.isfile(path / file):
-                # check if file has extension extension
-                # check if file basename has extension
-                if file.endswith(extension):
-                    filepath = path / file
-                    bids_files.append(filepath)
-
-        # check if file is in top level directory
+            if os.path.isfile(path / file) and file.endswith(extension):
+                bids_files.append(path / file)
+
         if any(file in os.listdir(path) for file in top_level_files):
             return bids_files
         else:
-            # call get_bids_file_inheritance recursively with parent directory
             bids_files.extend(
                 self._get_bids_file_inheritance(path.parent, basename, extension)
             )
             return bids_files
 
     def get_bids_metadata_files(
-        self, filepath: str | Path, metadata_file_extension: list[str]
+        self, filepath: str | Path, metadata_file_extension: str
     ) -> list[Path]:
-        """Retrieve all metadata file paths that apply to a given data file path and that
-        end with a specific suffix (following the BIDS inheritance principle).
+        """Retrieve all metadata files that apply to a given data file.
+
+        Follows the BIDS inheritance principle to find all relevant metadata
+        files (e.g., ``channels.tsv``, ``eeg.json``) for a specific recording.
 
         Parameters
         ----------
-        filepath: str | Path
-            The filepath to get the associated metadata files for.
+        filepath : str or Path
+            The path to the data file.
         metadata_file_extension : str
-            Consider only metadata files that end with the specified suffix,
-            e.g., channels.tsv or eeg.json
+            The extension of the metadata file to search for (e.g., "channels.tsv").
 
         Returns
         -------
-        list[Path]:
-            A list of filepaths for all matching metadata files
+        list of Path
+            A list of paths to the matching metadata files.
 
         """
         if isinstance(filepath, str):
             filepath = Path(filepath)
-        if not filepath.exists:
-            raise ValueError("filepath {filepath} does not exist")
+        if not filepath.exists():
+            raise ValueError(f"filepath {filepath} does not exist")
         path, filename = os.path.split(filepath)
         basename = filename[: filename.rfind("_")]
-        # metadata files
         meta_files = self._get_bids_file_inheritance(
             path, basename, metadata_file_extension
         )
         return meta_files
 
-    def _scan_directory(self, directory: str, extension: str) -> list[Path]:
-        """Return a list of file paths that end with the given extension in the specified
-        directory. Ignores certain special directories like .git, .datalad, derivatives,
-        and code.
+    def get_files(self) -> list[str]:
+        """Get all EEG recording file paths in the BIDS dataset.
+
+        Returns
+        -------
+        list of str
+            A list of file paths for all valid EEG recordings.
+
         """
-        result_files = []
-        directory_to_ignore = [".git", ".datalad", "derivatives", "code"]
-        with os.scandir(directory) as entries:
-            for entry in entries:
-                if entry.is_file() and entry.name.endswith(extension):
-                    result_files.append(entry.path)
-                elif entry.is_dir():
-                    # check that entry path doesn't contain any name in ignore list
-                    if not any(name in entry.name for name in directory_to_ignore):
-                        result_files.append(entry.path)  # Add directory to scan later
-        return result_files
-
-    def _get_files_with_extension_parallel(
-        self, directory: str, extension: str = ".set", max_workers: int = -1
-    ) -> list[Path]:
-        """Efficiently scan a directory and its subdirectories for files that end with
-        the given extension.
+        return self.files
+
+    def get_bids_file_attribute(self, attribute: str, data_filepath: str) -> Any:
+        """Retrieve a specific attribute from BIDS metadata.
 
         Parameters
         ----------
-        directory : str
-            The root directory to scan for files.
-        extension : str
-            Only consider files that end with this suffix, e.g. '.set'.
-        max_workers : int
-            Optionally specify the maximum number of worker threads to use for parallel scanning.
-            Defaults to all available CPU cores if set to -1.
+        attribute : str
+            The name of the attribute to retrieve (e.g., "sfreq", "subject").
+        data_filepath : str
+            The path to the data file.
 
         Returns
         -------
-        list[Path]:
-            A list of filepaths for all matching metadata files
+        Any
+            The value of the requested attribute, or None if not found.
 
         """
-        result_files = []
-        dirs_to_scan = [directory]
+        bids_path = self._get_bids_path_from_file(data_filepath)
+
+        # Direct BIDSPath properties for entities
+        direct_attrs = {
+            "subject": bids_path.subject,
+            "session": bids_path.session,
+            "task": bids_path.task,
+            "run": bids_path.run,
+            "modality": bids_path.datatype,
+        }
 
-        # Use joblib.Parallel and delayed to parallelize directory scanning
-        while dirs_to_scan:
-            logger.info(
-                f"Directories to scan: {len(dirs_to_scan)}, files: {dirs_to_scan}"
-            )
-            # Run the scan_directory function in parallel across directories
-            results = Parallel(n_jobs=max_workers, prefer="threads", verbose=1)(
-                delayed(self._scan_directory)(d, extension) for d in dirs_to_scan
-            )
+        if attribute in direct_attrs:
+            return direct_attrs[attribute]
 
-            # Reset the directories to scan and process the results
-            dirs_to_scan = []
-            for res in results:
-                for path in res:
-                    if os.path.isdir(path):
-                        dirs_to_scan.append(path)  # Queue up subdirectories to scan
-                    else:
-                        result_files.append(path)  # Add files to the final result
-            logger.info(f"Found {len(result_files)} files.")
-
-        return result_files
-
-    def load_and_preprocess_raw(
-        self, raw_file: str, preprocess: bool = False
-    ) -> np.ndarray:
-        """Utility function to load a raw data file with MNE and apply some simple
-        (hardcoded) preprocessing and return as a numpy array. Not meant for purposes
-        other than testing or debugging.
-        """
-        logger.info(f"Loading raw data from {raw_file}")
-        EEG = mne.io.read_raw_eeglab(raw_file, preload=True, verbose="error")
-
-        if preprocess:
-            # highpass filter
-            EEG = EEG.filter(l_freq=0.25, h_freq=25, verbose=False)
-            # remove 60Hz line noise
-            EEG = EEG.notch_filter(freqs=(60), verbose=False)
-            # bring to common sampling rate
-            sfreq = 128
-            if EEG.info["sfreq"] != sfreq:
-                EEG = EEG.resample(sfreq)
-
-        mat_data = EEG.get_data()
-
-        if len(mat_data.shape) > 2:
-            raise ValueError("Expect raw data to be CxT dimension")
-        return mat_data
-
-    def get_files(self) -> list[Path]:
-        """Get all EEG recording file paths (with valid extensions) in the BIDS folder."""
-        return self.files
+        # For JSON-based attributes, read and cache eeg.json
+        eeg_json = self._get_json_with_inheritance(data_filepath, "eeg.json")
+        json_attrs = {
+            "sfreq": eeg_json.get("SamplingFrequency"),
+            "ntimes": eeg_json.get("RecordingDuration"),
+            "nchans": eeg_json.get("EEGChannelCount"),
+        }
+
+        return json_attrs.get(attribute)
 
-    def resolve_bids_json(self, json_files: list[str]) -> dict:
-        """Resolve the BIDS JSON files and return a dictionary of the resolved values.
+    def channel_labels(self, data_filepath: str) -> list[str]:
+        """Get a list of channel labels from channels.tsv.
 
         Parameters
         ----------
-        json_files : list
-            A list of JSON file paths to resolve in order of leaf level first.
+        data_filepath : str
+            The path to the data file.
 
         Returns
         -------
-            dict: A dictionary of the resolved values.
+        list of str
+            A list of channel names.
 
         """
-        if len(json_files) == 0:
-            raise ValueError("No JSON files provided")
-        json_files.reverse()  # TODO undeterministic
+        # Find channels.tsv in the same directory as the data file
+        # It can be named either "channels.tsv" or "*_channels.tsv"
+        filepath = Path(data_filepath)
+        parent_dir = filepath.parent
+
+        # Try the standard channels.tsv first
+        channels_tsv_path = parent_dir / "channels.tsv"
+        if not channels_tsv_path.exists():
+            # Try to find *_channels.tsv matching the filename prefix
+            base_name = filepath.stem  # filename without extension
+            for tsv_file in parent_dir.glob("*_channels.tsv"):
+                # Check if it matches by looking at task/run components
+                tsv_name = tsv_file.stem.replace("_channels", "")
+                if base_name.startswith(tsv_name):
+                    channels_tsv_path = tsv_file
+                    break
+
+        if not channels_tsv_path.exists():
+            raise FileNotFoundError(f"No channels.tsv found for {data_filepath}")
+
+        channels_tsv = pd.read_csv(channels_tsv_path, sep="\t")
+        return channels_tsv["name"].tolist()
 
-        json_dict = {}
-        for json_file in json_files:
-            with open(json_file) as f:
-                json_dict.update(json.load(f))
-        return json_dict
+    def channel_types(self, data_filepath: str) -> list[str]:
+        """Get a list of channel types from channels.tsv.
 
-    def get_bids_file_attribute(self, attribute: str, data_filepath: str) -> Any:
-        """Retrieve a specific attribute from the BIDS file metadata applicable
-        to the provided recording file path.
-        """
-        entities = self.layout.parse_file_entities(data_filepath)
-        bidsfile = self.layout.get(**entities)[0]
-        attributes = bidsfile.get_entities(metadata="all")
-        attribute_mapping = {
-            "sfreq": "SamplingFrequency",
-            "modality": "datatype",
-            "task": "task",
-            "session": "session",
-            "run": "run",
-            "subject": "subject",
-            "ntimes": "RecordingDuration",
-            "nchans": "EEGChannelCount",
-        }
-        attribute_value = attributes.get(attribute_mapping.get(attribute), None)
-        return attribute_value
+        Parameters
+        ----------
+        data_filepath : str
+            The path to the data file.
 
-    def channel_labels(self, data_filepath: str) -> list[str]:
-        """Get a list of channel labels for the given data file path."""
-        channels_tsv = pd.read_csv(
-            self.get_bids_metadata_files(data_filepath, "channels.tsv")[0], sep="\t"
-        )
-        return channels_tsv["name"].tolist()
+        Returns
+        -------
+        list of str
+            A list of channel types.
 
-    def channel_types(self, data_filepath: str) -> list[str]:
-        """Get a list of channel types for the given data file path."""
-        channels_tsv = pd.read_csv(
-            self.get_bids_metadata_files(data_filepath, "channels.tsv")[0], sep="\t"
-        )
+        """
+        # Find channels.tsv in the same directory as the data file
+        # It can be named either "channels.tsv" or "*_channels.tsv"
+        filepath = Path(data_filepath)
+        parent_dir = filepath.parent
+
+        # Try the standard channels.tsv first
+        channels_tsv_path = parent_dir / "channels.tsv"
+        if not channels_tsv_path.exists():
+            # Try to find *_channels.tsv matching the filename prefix
+            base_name = filepath.stem  # filename without extension
+            for tsv_file in parent_dir.glob("*_channels.tsv"):
+                # Check if it matches by looking at task/run components
+                tsv_name = tsv_file.stem.replace("_channels", "")
+                if base_name.startswith(tsv_name):
+                    channels_tsv_path = tsv_file
+                    break
+
+        if not channels_tsv_path.exists():
+            raise FileNotFoundError(f"No channels.tsv found for {data_filepath}")
+
+        channels_tsv = pd.read_csv(channels_tsv_path, sep="\t")
         return channels_tsv["type"].tolist()
 
     def num_times(self, data_filepath: str) -> int:
-        """Get the approximate number of time points in the EEG recording based on the BIDS metadata."""
-        eeg_jsons = self.get_bids_metadata_files(data_filepath, "eeg.json")
-        eeg_json_dict = self._merge_json_inheritance(eeg_jsons)
+        """Get the number of time points in the recording.
+
+        Calculated from ``SamplingFrequency`` and ``RecordingDuration`` in eeg.json.
+
+        Parameters
+        ----------
+        data_filepath : str
+            The path to the data file.
+
+        Returns
+        -------
+        int
+            The approximate number of time points.
+
+        """
+        eeg_json_dict = self._get_json_with_inheritance(data_filepath, "eeg.json")
         return int(
-            eeg_json_dict["SamplingFrequency"] * eeg_json_dict["RecordingDuration"]
+            eeg_json_dict.get("SamplingFrequency", 0)
+            * eeg_json_dict.get("RecordingDuration", 0)
         )
 
     def subject_participant_tsv(self, data_filepath: str) -> dict[str, Any]:
-        """Get BIDS participants.tsv record for the subject to which the given file
-        path corresponds, as a dictionary.
+        """Get the participants.tsv record for a subject.
+
+        Parameters
+        ----------
+        data_filepath : str
+            The path to a data file belonging to the subject.
+
+        Returns
+        -------
+        dict
+            A dictionary of the subject's information from participants.tsv.
+
         """
-        participants_tsv = pd.read_csv(
-            self.get_bids_metadata_files(data_filepath, "participants.tsv")[0], sep="\t"
-        )
-        # if participants_tsv is not empty
+        participants_tsv_path = self.get_bids_metadata_files(
+            data_filepath, "participants.tsv"
+        )[0]
+        participants_tsv = pd.read_csv(participants_tsv_path, sep="\t")
         if participants_tsv.empty:
             return {}
-        # set 'participant_id' as index
         participants_tsv.set_index("participant_id", inplace=True)
         subject = f"sub-{self.get_bids_file_attribute('subject', data_filepath)}"
         return participants_tsv.loc[subject].to_dict()
 
     def eeg_json(self, data_filepath: str) -> dict[str, Any]:
-        """Get BIDS eeg.json metadata for the given data file path."""
-        eeg_jsons = self.get_bids_metadata_files(data_filepath, "eeg.json")
-        eeg_json_dict = self._merge_json_inheritance(eeg_jsons)
-        return eeg_json_dict
-
-    def channel_tsv(self, data_filepath: str) -> dict[str, Any]:
-        """Get BIDS channels.tsv metadata for the given data file path, as a dictionary
-        of lists and/or single values.
+        """Get the merged eeg.json metadata for a data file.
+
+        Parameters
+        ----------
+        data_filepath : str
+            The path to the data file.
+
+        Returns
+        -------
+        dict
+            The merged eeg.json metadata.
+
         """
-        channels_tsv = pd.read_csv(
-            self.get_bids_metadata_files(data_filepath, "channels.tsv")[0], sep="\t"
-        )
-        channel_tsv = channels_tsv.to_dict()
-        # 'name' and 'type' now have a dictionary of index-value. Convert them to list
-        for list_field in ["name", "type", "units"]:
-            channel_tsv[list_field] = list(channel_tsv[list_field].values())
-        return channel_tsv
+        return self._get_json_with_inheritance(data_filepath, "eeg.json")
 
 
 __all__ = ["EEGDashBaseDataset", "EEGBIDSDataset", "EEGDashBaseRaw"]