concatenate_recordings#

brainsets.utils.mne_utils.concatenate_recordings(recordings, max_gap=1.0, on_mismatch='raise', on_gap='warn', on_missing_meas_date='warn')[source]#

Concatenate a list of MNE Raw objects into one, validating metadata.

This function concatenates multiple MNE Raw recordings, prioritizing temporal order by default: recordings are sorted by measurement date before concatenation.

Channel validation (always enforced):

All recordings must have identical channel names and order.

Measurement date validation:

The function validates that all recordings have identical measurement days. The on_mismatch parameter controls how such mismatches are handled; default is “raise”.

If one or more recordings are missing a measurement date (meas_date is None), temporal order cannot be established. By default, the function will concatenate the recordings in the given input order rather than sorting by measurement date. The on_missing_meas_date parameter controls how this is handled; default is “warn”.

Offset validation:

The function checks for temporal offsets in the measurement dates of the recordings. If the measurement dates are separated by notable amounts of time (as defined by the max_gap parameter, in hours), this can indicate temporal discontinuity. The on_gap parameter controls how such offsets are handled when the offset exceeds max_gap; default is “warn”. This is useful to ensure recordings are truly continuous or to be notified about gaps between sessions.

Parameters:

  • recordings – List of MNE Raw objects to concatenate.

  • max_gap – Maximum allowed gap in hours between consecutive measurement dates for the recordings to be considered continuous.

  • on_mismatch – How to handle measurement date mismatches (channel mismatches always raise). - “raise”: raise ValueError if measurement days are not uniform (default), - “warn”: issue a warning and continue, - “ignore”: silently continue with measurement day mismatches.

  • on_gap – How to handle temporal offsets between recordings’ measurement dates. - “raise”: raise ValueError if offsets are detected, - “warn”: issue a warning and continue (default), - “ignore”: silently continue with offsets.

  • on_missing_meas_date – How to handle missing (None) measurement dates. - “raise”: raise ValueError if any measurement date is None, - “warn”: issue a warning and continue in input order (default), - “ignore”: silently continue in input order.

Returns:

An MNE Raw object containing the concatenated recordings in temporal order (or input order if measurement dates are missing or mixed).

Raises:

  • ImportError – If MNE is not installed.

  • ValueError – If recordings is empty, contains non-Raw objects, has channel mismatches, on_mismatch, on_gap, or on_missing_meas_date is invalid, or (if set to “raise”) measurement date mismatches, time offsets, or missing measurement dates are detected.