group_recordings_by_entity#

brainsets.utils.bids_utils.group_recordings_by_entity(recordings, fixed_entities=None)[source]#

Group BIDS-compliant recordings by specified fixed entities.

BIDS entities (e.g., subject, session, task) are standardized labels in BIDS filenames. For more information on BIDS entities, see: https://bids-specification.readthedocs.io/en/stable/appendices/entities.html

Group keys are constructed using only the entities listed in fixed_entities; all other entities are implicitly allowed to vary within a group.

By default (fixed_entities=None), groups are created by all entities except ‘run’.

Entities can be provided in long form (e.g., subject, session) or short BIDS form (e.g., sub, ses).

Parameters:

  • recordings (list[dict]) – List of recording dictionaries that include a recording_id key.

  • fixed_entities (Optional[list[str]]) – Entities that must remain fixed within each group. If None, all entities except run are kept in the grouping key.

Return type:

dict[str, list[dict]]

Returns:

Dictionary mapping a grouping key to the list of recordings in that group.

Raises:

ValueError – If an entity name is unsupported.