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)

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]]

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

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) → None

Scan a local BIDS dataset and upsert records into MongoDB.

Parameters:

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

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

• overwrite (bool, default True) – If True, update existing records when encountered; otherwise, skip records that already exist.

Raises:

ValueError – If called on a public client (is_public=True).

add(record: dict) → None

Add a single record to the MongoDB collection.

Parameters:

record (dict) – The record to add.

update(record: dict) → None

Update a single record in the MongoDB collection.

Parameters:

record (dict) – Record content to set at the matching data_name.

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

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

remove_field(record: dict, field: str) → None

Remove a field from a specific record in the MongoDB collection.

Parameters:

• record (dict) – Record-identifying object with a data_name key.

• field (str) – The name of the field to remove.

remove_field_from_db(field: str) → None

Remove a field from all records in the database.

Warning

This is a destructive operation and cannot be undone.

Parameters:

field (str) – The name of the field to remove from all documents.

property collection

The underlying PyMongo Collection object.

Returns:

The collection object used for database interactions.

Return type:

pymongo.collection.Collection

close() → None

Close the MongoDB connection.

Deprecated since version 0.1: Connections are now managed globally by MongoConnectionManager. This method is a no-op and will be removed in a future version. Use EEGDash.close_all_connections() to close all clients.

classmethod close_all_connections() → None

Close all MongoDB client connections managed by the singleton manager.