eegdash.bids_eeg_metadata#

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.

Functions

participants_row_for_subject(bids_root, subject)

Load participants.tsv and return the row for a specific subject.

participants_extras_from_tsv(bids_root, ...)

Extract additional participant information from participants.tsv.

attach_participants_extras(raw, description, ...)

Attach extra participant data to a raw object and its description.

enrich_from_participants(bids_root, ...)

Read participants.tsv and attach extra info for the subject.
eegdash.bids_eeg_metadata.participants_row_for_subject(bids_root: str | Path, subject: str, id_columns: tuple[str, ...] = ('participant_id', 'participant', 'subject')) → Series | None[source]#

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:

A pandas Series containing the subject’s data if found, otherwise None.

Return type:

pandas.Series or None

eegdash.bids_eeg_metadata.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][source]#

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:

A dictionary of extra participant information.

Return type:

dict

eegdash.bids_eeg_metadata.attach_participants_extras(raw: Any, description: Any, extras: dict[str, Any]) → None[source]#

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.

eegdash.bids_eeg_metadata.enrich_from_participants(bids_root: str | Path, bidspath: BIDSPath, raw: Any, description: Any) → dict[str, Any][source]#

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:

The dictionary of extras that were attached.

Return type:

dict