eegdash 0.3.4.dev70__tar.gz → 0.3.5.dev80__tar.gz

{eegdash-0.3.4.dev70/eegdash.egg-info → eegdash-0.3.5.dev80}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.3.4.dev70
+Version: 0.3.5.dev80
 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
@@ -38,6 +38,7 @@ Requires-Dist: tqdm
 Requires-Dist: xarray
 Requires-Dist: h5io>=0.2.4
 Requires-Dist: pymatreader
+Requires-Dist: eeglabio
 Requires-Dist: tabulate
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"

{eegdash-0.3.4.dev70 → eegdash-0.3.5.dev80}/docs/source/conf.py

@@ -123,7 +123,7 @@ sphinx_gallery_conf = {
     "subsection_order": ExplicitOrder(
         [
             f"{EX_DIR}/core",
-            f"{EX_DIR}/eeg2025",
+            # f"{EX_DIR}/eeg2025",
             "*",
         ]
     ),

{eegdash-0.3.4.dev70 → eegdash-0.3.5.dev80}/docs/source/index.rst

@@ -49,6 +49,7 @@ research for machine learning and deep learning applications.
 .. toctree::
    :hidden:
 
+   Overview <overview>
    Install <install/install>
    API <api/modules.rst>
    Dataset Summary <dataset_summary>

eegdash-0.3.5.dev80/docs/source/overview.rst

@@ -0,0 +1,37 @@
+.. _overview:
+
+========
+Overview
+========
+
+eegdash is an interface designed to streamline the access and use of EEG data for machine learning applications. It is composed of three main components that work together to provide a seamless experience for researchers and developers.
+
+The architecture of eegdash can be visualized as follows:
+
+.. code-block:: text
+
+      +-----------------+
+      |     MongoDB     |
+      |    (Metadata)   |
+      +-----------------+
+            |
+            |
+      +-----------v-----------+      +-----------------+
+      |       eegdash         |<---->|   S3 Filesystem |
+      |     Interface         |      |    (Raw Data)   |
+      +-----------------------+      +-----------------+
+            |
+            |
+      +-----------v-----------+
+      |      BIDS Parser      |
+      +-----------------------+
+
+
+
+The components are:
+
+* **MongoDB**: This is a NoSQL database that centralizes all the metadata related to the EEG datasets. It stores information about subjects, sessions, tasks, and other relevant details, allowing for fast and efficient querying.
+
+* **S3 Filesystem**: The raw EEG data is stored in an S3-compatible object storage. This allows for scalable and reliable storage of large datasets. eegdash interacts with the S3 filesystem to download the data when it is needed.
+
+* **BIDS Parser**: The BIDS (Brain Imaging Data Structure) parser is responsible for interpreting the structure of the datasets. It ensures that the data is organized in a standardized way, making it easier to work with and understand.

{eegdash-0.3.4.dev70 → eegdash-0.3.5.dev80}/eegdash/__init__.py

@@ -7,4 +7,4 @@ __init__mongo_client()
 
 __all__ = ["EEGDash", "EEGDashDataset", "EEGChallengeDataset"]
 
-__version__ = "0.3.4.dev70"
+__version__ = "0.3.5.dev80"

{eegdash-0.3.4.dev70 → eegdash-0.3.5.dev80}/eegdash/api.py

@@ -9,6 +9,7 @@ import numpy as np
 import xarray as xr
 from dotenv import load_dotenv
 from joblib import Parallel, delayed
+from mne_bids import get_bids_path_from_fname, read_raw_bids
 from pymongo import InsertOne, UpdateOne
 from s3fs import S3FileSystem
 
@@ -34,6 +35,19 @@ class EEGDash:
 
     """
 
+    _ALLOWED_QUERY_FIELDS = {
+        "data_name",
+        "dataset",
+        "subject",
+        "task",
+        "session",
+        "run",
+        "modality",
+        "sampling_frequency",
+        "nchans",
+        "ntimes",
+    }
+
     def __init__(self, *, is_public: bool = True, is_staging: bool = False) -> None:
         """Create new instance of the EEGDash Database client.
 
@@ -71,34 +85,59 @@ class EEGDash:
             anon=True, client_kwargs={"region_name": "us-east-2"}
         )
 
-    def find(self, query: dict[str, Any], *args, **kwargs) -> list[Mapping[str, Any]]:
-        """Find records in the MongoDB collection that satisfy the given query.
+    def find(
+        self, query: dict[str, Any] = None, /, **kwargs
+    ) -> list[Mapping[str, Any]]:
+        """Find records in the MongoDB collection.
+
+        This method can be called in two ways:
+        1. With a pre-built MongoDB query dictionary (positional argument):
+           >>> eegdash.find({"dataset": "ds002718", "subject": {"$in": ["012", "013"]}})
+        2. With user-friendly keyword arguments for simple and multi-value queries:
+           >>> eegdash.find(dataset="ds002718", subject="012")
+           >>> eegdash.find(dataset="ds002718", subject=["012", "013"])
 
         Parameters
         ----------
-        query: dict
-            A dictionary that specifies the query to be executed; this is a reference
-            document that is used to match records in the MongoDB collection.
-        args:
-            Additional positional arguments for the MongoDB find() method; see
-            https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.find
-        kwargs:
-            Additional keyword arguments for the MongoDB find() method.
+        query: dict, optional
+            A complete MongoDB query dictionary. This is a positional-only argument.
+        **kwargs:
+            Keyword arguments representing field-value pairs for the query.
+            Values can be single items (str, int) or lists of items for multi-search.
 
         Returns
         -------
         list:
             A list of DB records (string-keyed dictionaries) that match the query.
 
-        Example
-        -------
-        >>> eegdash = EEGDash()
-        >>> eegdash.find({"dataset": "ds002718", "subject": "012"})
+        Raises
+        ------
+        ValueError
+            If both a `query` dictionary and keyword arguments are provided.
 
         """
-        results = self.__collection.find(query, *args, **kwargs)
+        if query is not None and kwargs:
+            raise ValueError(
+                "Provide either a positional 'query' dictionary or keyword arguments, not both."
+            )
 
-        return [result for result in results]
+        final_query = {}
+        if query is not None:
+            final_query = query
+        elif kwargs:
+            final_query = self._build_query_from_kwargs(**kwargs)
+        else:
+            # By default, an empty query {} returns all documents.
+            # This can be dangerous, so we can either allow it or raise an error.
+            # Let's require an explicit query for safety.
+            raise ValueError(
+                "find() requires a query dictionary or at least one keyword argument. "
+                "To find all documents, use find({})."
+            )
+
+        results = self.__collection.find(final_query)
+
+        return list(results)
 
     def exist(self, query: dict[str, Any]) -> bool:
         """Return True if at least one record matches the query, else False.
@@ -184,6 +223,35 @@ class EEGDash:
 
         return record
 
+    def _build_query_from_kwargs(self, **kwargs) -> dict[str, Any]:
+        """Builds and validates a MongoDB query from user-friendly keyword arguments.
+
+        Translates list values into MongoDB's `$in` operator.
+        """
+        # 1. Validate that all provided keys are allowed for querying
+        unknown_fields = set(kwargs.keys()) - self._ALLOWED_QUERY_FIELDS
+        if unknown_fields:
+            raise ValueError(
+                f"Unsupported query field(s): {', '.join(sorted(unknown_fields))}. "
+                f"Allowed fields are: {', '.join(sorted(self._ALLOWED_QUERY_FIELDS))}"
+            )
+
+        # 2. Construct the query dictionary
+        query = {}
+        for key, value in kwargs.items():
+            if isinstance(value, (list, tuple)):
+                if not value:
+                    raise ValueError(
+                        f"Received an empty list for query parameter '{key}'. This is not supported."
+                    )
+                # If the value is a list, use the `$in` operator for multi-search
+                query[key] = {"$in": value}
+            else:
+                # Otherwise, it's a direct match
+                query[key] = value
+
+        return query
+
     def load_eeg_data_from_s3(self, s3path: str) -> xr.DataArray:
         """Load an EEGLAB .set file from an AWS S3 URI and return it as an xarray DataArray.
 
@@ -218,14 +286,15 @@ class EEGDash:
         Parameters
         ----------
         bids_file : str
-            Path to the file on the local filesystem.
+            Path to the BIDS-compliant file on the local filesystem.
 
         Notes
         -----
         Currently, only non-epoched .set files are supported.
 
         """
-        raw_object = mne.io.read_raw(bids_file)
+        bids_path = get_bids_path_from_fname(bids_file, verbose=False)
+        raw_object = read_raw_bids(bids_path=bids_path, verbose=False)
         eeg_data = raw_object.get_data()
 
         fs = raw_object.info["sfreq"]
@@ -521,8 +590,8 @@ class EEGDashDataset(BaseConcatDataset):
     def __init__(
         self,
         query: dict | None = None,
-        data_dir: str | list | None = None,
-        dataset: str | list | None = None,
+        cache_dir: str = "~/eegdash_cache",
+        dataset: str | None = None,
         description_fields: list[str] = [
             "subject",
             "session",
@@ -532,36 +601,55 @@ class EEGDashDataset(BaseConcatDataset):
             "gender",
             "sex",
         ],
-        cache_dir: str = "~/eegdash_cache",
         s3_bucket: str | None = None,
+        data_dir: str | None = None,
         eeg_dash_instance=None,
+        records: list[dict] | None = None,
         **kwargs,
     ):
         """Create a new EEGDashDataset from a given query or local BIDS dataset directory
         and dataset name. An EEGDashDataset is pooled collection of EEGDashBaseDataset
         instances (individual recordings) and is a subclass of braindecode's BaseConcatDataset.
 
+
+        Querying Examples:
+        ------------------
+        # Find by single subject
+        >>> ds = EEGDashDataset(dataset="ds005505", subject="NDARCA153NKE")
+
+        # Find by a list of subjects and a specific task
+        >>> subjects = ["NDARCA153NKE", "NDARXT792GY8"]
+        >>> ds = EEGDashDataset(dataset="ds005505", subject=subjects, task="RestingState")
+
+        # Use a raw MongoDB query for advanced filtering
+        >>> raw_query = {"dataset": "ds005505", "subject": {"$in": subjects}}
+        >>> ds = EEGDashDataset(query=raw_query)
+
         Parameters
         ----------
         query : dict | None
-            Optionally a dictionary that specifies the query to be executed; see
-            EEGDash.find() for details on the query format.
-        data_dir : str | list[str] | None
-            Optionally a string or a list of strings specifying one or more local
-            BIDS dataset directories from which to load the EEG data files. Exactly one
+            A raw MongoDB query dictionary. If provided, keyword arguments for filtering are ignored.
+        **kwargs : dict
+            Keyword arguments for filtering (e.g., `subject="X"`, `task=["T1", "T2"]`) and/or
+            arguments to be passed to the EEGDashBaseDataset constructor (e.g., `subject=...`).
+        cache_dir : str
+            A directory where the dataset will be cached locally.
+        data_dir : str | None
+            Optionally a string specifying a local BIDS dataset directory from which to load the EEG data files. Exactly one
             of query or data_dir must be provided.
-        dataset : str | list[str] | None
-            If data_dir is given, a name or list of names for for the dataset(s) to be loaded.
+        dataset : str | None
+            If data_dir is given, a name for the dataset to be loaded.
         description_fields : list[str]
             A list of fields to be extracted from the dataset records
             and included in the returned data description(s). Examples are typical
             subject metadata fields such as "subject", "session", "run", "task", etc.;
             see also data_config.description_fields for the default set of fields.
-        cache_dir : str
-            A directory where the dataset will be cached locally.
         s3_bucket : str | None
             An optional S3 bucket URI (e.g., "s3://mybucket") to use instead of the
             default OpenNeuro bucket for loading data files
+        records : list[dict] | None
+            Optional list of pre-fetched metadata records. If provided, the dataset is
+            constructed directly from these records without querying MongoDB.
         kwargs : dict
             Additional keyword arguments to be passed to the EEGDashBaseDataset
             constructor.
@@ -569,50 +657,79 @@ class EEGDashDataset(BaseConcatDataset):
         """
         self.cache_dir = cache_dir
         self.s3_bucket = s3_bucket
-        self.eeg_dash = eeg_dash_instance or EEGDash()
-        _owns_client = eeg_dash_instance is None
+        self.eeg_dash = eeg_dash_instance
+        _owns_client = False
+        if self.eeg_dash is None and records is None:
+            self.eeg_dash = EEGDash()
+            _owns_client = True
+
+        # Separate query kwargs from other kwargs passed to the BaseDataset constructor
+        query_kwargs = {
+            k: v for k, v in kwargs.items() if k in EEGDash._ALLOWED_QUERY_FIELDS
+        }
+        base_dataset_kwargs = {k: v for k, v in kwargs.items() if k not in query_kwargs}
+
+        if query and query_kwargs:
+            raise ValueError(
+                "Provide either a 'query' dictionary or keyword arguments for filtering, not both."
+            )
 
         try:
-            if query:
-                datasets = self.find_datasets(query, description_fields, **kwargs)
+            if records is not None:
+                self.records = records
+                datasets = [
+                    EEGDashBaseDataset(
+                        record,
+                        self.cache_dir,
+                        self.s3_bucket,
+                        **base_dataset_kwargs,
+                    )
+                    for record in self.records
+                ]
             elif data_dir:
-                if isinstance(data_dir, str):
+                # This path loads from a local directory and is not affected by DB query logic
+                if isinstance(data_dir, str) or isinstance(data_dir, Path):
                     datasets = self.load_bids_dataset(
-                        dataset, data_dir, description_fields, s3_bucket, **kwargs
+                        dataset=dataset,
+                        data_dir=data_dir,
+                        description_fields=description_fields,
+                        s3_bucket=s3_bucket,
+                        **base_dataset_kwargs,
                     )
                 else:
                     assert len(data_dir) == len(dataset), (
-                        "Number of datasets and their directories must match"
+                        "Number of datasets and directories must match"
                     )
                     datasets = []
                     for i, _ in enumerate(data_dir):
                         datasets.extend(
                             self.load_bids_dataset(
-                                dataset[i],
-                                data_dir[i],
-                                description_fields,
-                                s3_bucket,
-                                **kwargs,
+                                dataset=dataset[i],
+                                data_dir=data_dir[i],
+                                description_fields=description_fields,
+                                s3_bucket=s3_bucket,
+                                **base_dataset_kwargs,
                             )
                         )
+            elif query or query_kwargs:
+                # This is the DB query path that we are improving
+                datasets = self.find_datasets(
+                    query=query,
+                    description_fields=description_fields,
+                    query_kwargs=query_kwargs,
+                    base_dataset_kwargs=base_dataset_kwargs,
+                )
+                # We only need filesystem if we need to access S3
+                self.filesystem = S3FileSystem(
+                    anon=True, client_kwargs={"region_name": "us-east-2"}
+                )
             else:
                 raise ValueError(
-                    "Exactly one of 'query' or 'data_dir' must be provided."
+                    "You must provide either 'records', a 'data_dir', or a query/keyword arguments for filtering."
                 )
         finally:
-            # If we created the client, close it now that construction is done.
-            if _owns_client:
-                try:
-                    self.eeg_dash.close()
-                except Exception:
-                    # Don't let close errors break construction
-                    pass
-
-        self.filesystem = S3FileSystem(
-            anon=True, client_kwargs={"region_name": "us-east-2"}
-        )
-
-        self.eeg_dash.close()
+            if _owns_client and self.eeg_dash is not None:
+                self.eeg_dash.close()
 
         super().__init__(datasets)
 
@@ -630,7 +747,11 @@ class EEGDashDataset(BaseConcatDataset):
         return None
 
     def find_datasets(
-        self, query: dict[str, Any], description_fields: list[str], **kwargs
+        self,
+        query: dict[str, Any],
+        description_fields: list[str],
+        query_kwargs: dict,
+        base_dataset_kwargs: dict,
     ) -> list[EEGDashBaseDataset]:
         """Helper method to find datasets in the MongoDB collection that satisfy the
         given query and return them as a list of EEGDashBaseDataset objects.
@@ -652,7 +773,10 @@ class EEGDashDataset(BaseConcatDataset):
 
         """
         datasets: list[EEGDashBaseDataset] = []
-        for record in self.eeg_dash.find(query):
+
+        self.records = self.eeg_dash.find(query, **query_kwargs)
+
+        for record in self.records:
             description = {}
             for field in description_fields:
                 value = self.find_key_in_nested_dict(record, field)
@@ -664,15 +788,15 @@ class EEGDashDataset(BaseConcatDataset):
                     self.cache_dir,
                     self.s3_bucket,
                     description=description,
-                    **kwargs,
+                    **base_dataset_kwargs,
                 )
             )
         return datasets
 
     def load_bids_dataset(
         self,
-        dataset,
-        data_dir,
+        dataset: str,
+        data_dir: str | Path,
         description_fields: list[str],
         s3_bucket: str | None = None,
         **kwargs,

{eegdash-0.3.4.dev70 → eegdash-0.3.5.dev80/eegdash.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.3.4.dev70
+Version: 0.3.5.dev80
 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
@@ -38,6 +38,7 @@ Requires-Dist: tqdm
 Requires-Dist: xarray
 Requires-Dist: h5io>=0.2.4
 Requires-Dist: pymatreader
+Requires-Dist: eeglabio
 Requires-Dist: tabulate
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"

{eegdash-0.3.4.dev70 → eegdash-0.3.5.dev80}/eegdash.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ docs/Makefile
 docs/source/conf.py
 docs/source/dataset_summary.rst
 docs/source/index.rst
+docs/source/overview.rst
 docs/source/install/install.rst
 docs/source/install/install_pip.rst
 docs/source/install/install_source.rst
@@ -39,10 +40,13 @@ eegdash/features/feature_bank/dimensionality.py
 eegdash/features/feature_bank/signal.py
 eegdash/features/feature_bank/spectral.py
 eegdash/features/feature_bank/utils.py
+tests/test_api.py
 tests/test_correctness.py
 tests/test_dataset.py
 tests/test_dataset_registration.py
 tests/test_eegdash.py
 tests/test_functional.py
 tests/test_init.py
-tests/test_mongo_connection.py
+tests/test_mongo_connection.py
+tests/test_offline.py
+tests/test_query.py

{eegdash-0.3.4.dev70 → eegdash-0.3.5.dev80}/eegdash.egg-info/requires.txt

@@ -12,6 +12,7 @@ tqdm
 xarray
 h5io>=0.2.4
 pymatreader
+eeglabio
 tabulate
 
 [all]

{eegdash-0.3.4.dev70 → eegdash-0.3.5.dev80}/pyproject.toml

@@ -49,6 +49,7 @@ dependencies = [
   "xarray",
   "h5io >= 0.2.4",
   "pymatreader",
+  "eeglabio",
   "tabulate",
 ]
 

eegdash-0.3.5.dev80/tests/test_api.py

@@ -0,0 +1,63 @@
+import mne
+import numpy as np
+import pytest
+import xarray as xr
+from mne_bids import BIDSPath, write_raw_bids
+
+from eegdash.api import EEGDash
+
+
+# Fixture to create a dummy BIDS dataset for testing
+@pytest.fixture(scope="module")
+def dummy_bids_dataset(tmpdir_factory):
+    bids_root = tmpdir_factory.mktemp("bids")
+    # Create a simple MNE Raw object
+    ch_names = ["EEG 001", "EEG 002", "EEG 003"]
+    ch_types = ["eeg"] * 3
+    sfreq = 100
+    n_times = 100
+    data = np.random.randn(len(ch_names), n_times)
+    info = mne.create_info(ch_names=ch_names, sfreq=sfreq, ch_types=ch_types)
+    raw = mne.io.RawArray(data, info)
+
+    # Define BIDS path
+    subject_id = "01"
+    session_id = "01"
+    task_name = "test"
+    run_id = "01"
+    bids_path = BIDSPath(
+        subject=subject_id,
+        session=session_id,
+        task=task_name,
+        run=run_id,
+        root=bids_root,
+        datatype="eeg",
+    )
+
+    # Write BIDS data
+    write_raw_bids(raw, bids_path, overwrite=True, format="EEGLAB", allow_preload=True)
+
+    return str(bids_path.fpath)
+
+
+def test_load_eeg_data_from_bids_file(dummy_bids_dataset):
+    eegdash = EEGDash()
+    data = eegdash.load_eeg_data_from_bids_file(dummy_bids_dataset)
+    assert isinstance(data, xr.DataArray)
+
+
+def test_load_eeg_data_from_bids_file_content(dummy_bids_dataset):
+    eegdash = EEGDash()
+    data = eegdash.load_eeg_data_from_bids_file(dummy_bids_dataset)
+
+    # Check dimensions
+    assert data.dims == ("channel", "time")
+
+    # Check shape
+    assert data.shape == (3, 100)
+
+    # Check channel names
+    assert list(data.channel.values) == ["EEG 001", "EEG 002", "EEG 003"]
+
+    # Check time values
+    assert len(data.time.values) == 100

eegdash-0.3.5.dev80/tests/test_offline.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+import pytest
+
+from eegdash import EEGDash, EEGDashDataset
+
+CACHE_DIR = (Path.home() / "mne_data" / "eeg_challenge_cache").resolve()
+CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def test_dataset_loads_without_eegdash(monkeypatch):
+    """Dataset should load from records without contacting network resources."""
+    eeg_dash = EEGDash()
+
+    records = eeg_dash.find(subject="NDARAC350XUM", task="RestingState")
+
+    # test with internet
+    dataset_internet = EEGDashDataset(
+        query=dict(task="RestingState", subject="NDARAC350XUM", dataset="ds005509"),
+        cache_dir=CACHE_DIR,
+        eeg_dash_instance=eeg_dash,
+    )
+
+    # Monkeypatch any network calls inside EEGDashDataset to raise if called
+    monkeypatch.setattr(
+        EEGDashDataset,
+        "find_datasets",
+        lambda *args, **kwargs: pytest.skip(
+            "Skipping network download in offline test"
+        ),
+    )
+    monkeypatch.setattr(
+        EEGDashDataset,
+        "find_datasets",
+        lambda *args, **kwargs: pytest.skip(
+            "Skipping network download in offline test"
+        ),
+    )
+    # TO-DO: discover way to do this pytest
+
+    dataset_without_internet = EEGDashDataset(
+        records=records, cache_dir=CACHE_DIR, eeg_dash_instance=None
+    )
+
+    assert dataset_internet.datasets[0].raw == dataset_without_internet.datasets[0].raw
+    assert (
+        dataset_internet.datasets[0].record
+        == dataset_without_internet.datasets[0].record
+    )

eegdash-0.3.5.dev80/tests/test_query.py

@@ -0,0 +1,85 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from eegdash import EEGDash
+
+
+# Mock the MongoConnectionManager to prevent actual DB connections during tests
+@pytest.fixture(autouse=True)
+def mock_mongo_connection():
+    """Automatically mocks the MongoDB connection for all tests."""
+    with patch("eegdash.mongodb.MongoConnectionManager.get_client") as mock_get_client:
+        mock_collection = MagicMock()
+        mock_db = MagicMock()
+        mock_client = MagicMock()
+        mock_get_client.return_value = (mock_client, mock_db, mock_collection)
+        yield mock_collection
+
+
+@pytest.fixture
+def eegdash_instance(mock_mongo_connection):
+    """Provides a clean instance of EEGDash for each test."""
+    return EEGDash(is_public=True)
+
+
+def test_build_query_with_single_values(eegdash_instance):
+    """Test 1: Validates that the query builder correctly handles simple
+    key-value pairs.
+    """
+    kwargs = {"dataset": "ds001", "subject": "sub-01"}
+    expected_query = {"dataset": "ds001", "subject": "sub-01"}
+
+    # _build_query_from_kwargs is a protected method, but we test it
+    # to ensure the core logic is sound.
+    query = eegdash_instance._build_query_from_kwargs(**kwargs)
+
+    assert query == expected_query
+
+
+def test_build_query_with_list_value(eegdash_instance):
+    """Test 2: Validates that the query builder correctly translates a list
+    of values into a MongoDB `$in` operator.
+    """
+    kwargs = {"dataset": "ds002", "subject": ["sub-01", "sub-02", "sub-03"]}
+    expected_query = {
+        "dataset": "ds002",
+        "subject": {"$in": ["sub-01", "sub-02", "sub-03"]},
+    }
+
+    query = eegdash_instance._build_query_from_kwargs(**kwargs)
+
+    assert query == expected_query
+
+
+def test_build_query_with_invalid_field(eegdash_instance):
+    """Test 3: Ensures the query builder raises a ValueError when an unsupported
+    query field is provided.
+    """
+    kwargs = {"dataset": "ds003", "invalid_field": "some_value"}
+
+    with pytest.raises(
+        ValueError, match="Unsupported query field\\(s\\): invalid_field"
+    ):
+        eegdash_instance._build_query_from_kwargs(**kwargs)
+
+
+def test_find_method_with_kwargs(eegdash_instance, mock_mongo_connection):
+    """Test 4: Verifies that the `find` method correctly uses the query builder
+    and calls the underlying database collection with the constructed query.
+    """
+    # Mock the return value of the collection's find method
+    mock_mongo_connection.find.return_value = [{"_id": "123", "dataset": "ds004"}]
+
+    # Call the method with user-friendly kwargs
+    results = eegdash_instance.find(dataset="ds004", subject=["sub-05", "sub-06"])
+
+    # Define the query we expect to be built and passed to the DB
+    expected_db_query = {"dataset": "ds004", "subject": {"$in": ["sub-05", "sub-06"]}}
+
+    # Assert that the collection's find method was called once with the correct query
+    mock_mongo_connection.find.assert_called_once_with(expected_db_query)
+
+    # Assert that the method returned the mocked data
+    assert len(results) == 1
+    assert results[0]["dataset"] == "ds004"