eegdash.api#

High-level interface to the EEGDash metadata database.

This module provides the main EEGDash class which serves as the primary entry point for interacting with the EEGDash ecosystem. It offers methods to query, insert, and update metadata records stored in the EEGDash MongoDB database, and includes utilities to load EEG data from S3 for matched records.

Classes

EEGDash(*[, is_public, is_staging])

High-level interface to the EEGDash metadata database.
class eegdash.api.EEGDash(*, is_public: bool = True, is_staging: bool = False)[source]#

Bases: object

High-level interface to the EEGDash metadata database.

Provides methods to query, insert, and update metadata records stored in the EEGDash MongoDB database (public or private). Also includes utilities to load EEG data from S3 for matched records.

For working with collections of recordings as PyTorch datasets, prefer EEGDashDataset.

Create a new EEGDash client.

Parameters:

  • is_public (bool, default True) – Connect to the public MongoDB database. If False, connect to a private database instance using the DB_CONNECTION_STRING environment variable (or value from a .env file).

  • is_staging (bool, default False) – If True, use the staging database (eegdashstaging); otherwise use the production database (eegdash).

Examples

>>> eegdash = EEGDash()
find(query: dict[str, Any] = None, /, **kwargs) → list[Mapping[str, Any]][source]#

Find records in the MongoDB collection.

Examples

>>> eegdash.find({"dataset": "ds002718", "subject": {"$in": ["012", "013"]}})  # pre-built query
>>> eegdash.find(dataset="ds002718", subject="012")  # keyword filters
>>> eegdash.find(dataset="ds002718", subject=["012", "013"])  # sequence -> $in
>>> eegdash.find({})  # fetch all (use with care)
>>> eegdash.find({"dataset": "ds002718"}, subject=["012", "013"])  # combine query + kwargs (AND)
Parameters:

  • query (dict, optional) – Complete MongoDB query dictionary. This is a positional-only argument.

  • **kwargs – User-friendly field filters that are converted to a MongoDB query. Values can be scalars (e.g., "sub-01") or sequences (translated to $in queries).

Returns:

DB records that match the query.

Return type:

list of dict

exist(query: dict[str, Any]) → bool[source]#

Return True if at least one record matches the query, else False.

This is a lightweight existence check that uses MongoDB’s find_one instead of fetching all matching documents (which would be wasteful in both time and memory for broad queries). Only a restricted set of fields is accepted to avoid accidental full scans caused by malformed or unsupported keys.

Parameters:

query (dict) – Mapping of allowed field(s) to value(s). Allowed keys: data_name and dataset. The query must not be empty.

Returns:

True if at least one matching record exists; False otherwise.

Return type:

bool

Raises:

  • TypeError – If query is not a dict.

  • ValueError – If query is empty or contains unsupported field names.

add_bids_dataset(dataset: str, data_dir: str, overwrite: bool = True, output_path: str | Path | None = None) → dict[str, Any][source]#

Collect metadata for a local BIDS dataset as JSON-ready records.

Instead of inserting records directly into MongoDB, this method scans data_dir and returns a JSON-serializable manifest describing every EEG recording that was discovered. The manifest can be written to disk or forwarded to the EEGDash ingestion API for persistence.

Parameters:

  • dataset (str) – Dataset identifier (e.g., "ds002718").

  • data_dir (str) – Path to the local BIDS dataset directory.

  • overwrite (bool, default True) – If False, skip records that already exist in the database based on data_name lookups.

  • output_path (str | Path | None, optional) – If provided, the manifest is written to the given JSON file.

Returns:

A manifest with keys dataset, source, records and, when applicable, skipped or errors.

Return type:

dict

exists(query: dict[str, Any]) → bool[source]#

Check if at least one record matches the query.

This is an alias for exist().

Parameters:

query (dict) – MongoDB query to check for existence.

Returns:

True if a matching record exists, False otherwise.

Return type:

bool

property collection#

The underlying PyMongo Collection object.

Returns:

The collection object used for database interactions.

Return type:

pymongo.collection.Collection

classmethod close_all_connections() → None[source]#

Close all MongoDB client connections managed by the singleton manager.