bemobil_mne.io.XDFLoader#

class bemobil_mne.io.XDFLoader(eeg_stream_name=None, eeg_stream_type='EEG', eeg_source_id=None, marker_stream_types=None, special_streams=None, tier2_streams=None, montage=None, old_reference=None, keep_channels=None, drop_channels=None, target_sfreq=None, alignment_method='pchip', max_nan_gap_s=None, on_mismatch='crop')[source]#

Bases: object

Multimodal XDF loader for MoBI and physiological recordings.

Streams are split into two tiers:

Tier 1 – continuous physiological streams merged into an MNE Raw object at a common target_sfreq. Includes EEG (primary), plus any streams listed in special_streams (ECG, EMG, eye-tracking, EDA, …).

Tier 2 – high-rate or frame-based streams kept at their native sampling rate and returned separately as {label: (data, timestamps_s)}. Intended for audio (requiring time-frequency analysis at full bandwidth) and video (raw frames).

Irregular streams (nominal_srate == 0) – e.g. fixation events, saccade events, custom triggers – are routed to the events dict rather than either tier.

Parameters:
eeg_stream_namestr, optional

Name of the EEG stream to load.

eeg_stream_typestr

LSL type of the EEG stream. Default: "EEG".

eeg_source_idstr, optional

Source ID of the EEG stream.

marker_stream_typeslist[str]

LSL types to scan for marker / annotation streams. Default: ["Markers", "Logging", "Notes"].

special_streamsdict, optional

Tier-1 auxiliary streams to align and merge into the Raw object. Format: {label: {"name": <str>, "type": <str>, "method": <str>}}. The optional "method" key overrides alignment_method for that stream only, allowing per-stream control (e.g. "sinc" for ECG at 1000 Hz while EDA uses "pchip" and a button box uses "stim"). Examples: ECG amplifier, eye-tracking gaze, EMG, EDA device.

tier2_streamsdict, optional

Tier-2 streams kept at native rate (not merged into Raw). Same format as special_streams ("method" key is ignored here). Examples: audio at 44.1 kHz, video stream.

montagestr, Path, or DigMontage, optional

Montage applied to EEG channels.

old_referencestr, optional

Reference channel to restore before setting montage (e.g. "FCz").

keep_channelslist[str], optional

Channel names or types to keep; all others are dropped.

drop_channelslist[str], optional

Channel names or types to drop.

target_sfreqfloat, optional

Common sampling frequency for all Tier-1 streams. EEG is resampled to this rate via MNE’s anti-aliased resample; auxiliary streams are aligned to the resulting time grid. Defaults to the EEG stream’s native rate if not set.

alignment_method{‘linear’, ‘pchip’, ‘sinc’, ‘nearest’, ‘stim’}

Default interpolation method for all Tier-1 auxiliary streams. Can be overridden per stream via the "method" key in special_streams. Default: 'pchip'.

max_nan_gap_sfloat or None

NaN gaps longer than this (seconds) in auxiliary streams are preserved in the output rather than bridged. None fills all gaps.

on_mismatch{‘crop’, ‘pad’}

Behaviour when auxiliary streams do not fully cover the EEG time range.

'crop' – trim the recording to the intersection of all Tier-1 stream time ranges. Safe when losing a few edge seconds is acceptable.

'pad' – keep the full EEG time range; auxiliary streams that do not cover the edges receive np.nan there (zeroed in Raw, marked with BAD_<label>_missing annotations). Preferable for continuous recordings where trimming would discard usable data.

Parameters:

  • eeg_stream_name (str | None)

  • eeg_stream_type (str)

  • eeg_source_id (str | None)

  • marker_stream_types (list[str] | None)

  • special_streams (dict[str, dict] | None)

  • tier2_streams (dict[str, dict] | None)

  • montage (str | mne.channels.DigMontage | None)

  • old_reference (str | None)

  • keep_channels (list[str] | None)

  • drop_channels (list[str] | None)

  • target_sfreq (float | None)

  • alignment_method (Literal['linear', 'pchip', 'sinc', 'nearest', 'stim'])

  • max_nan_gap_s (float | None)

  • on_mismatch (Literal['crop', 'pad'])

__init__(eeg_stream_name=None, eeg_stream_type='EEG', eeg_source_id=None, marker_stream_types=None, special_streams=None, tier2_streams=None, montage=None, old_reference=None, keep_channels=None, drop_channels=None, target_sfreq=None, alignment_method='pchip', max_nan_gap_s=None, on_mismatch='crop')[source]#
Parameters:

  • eeg_stream_name (str | None)

  • eeg_stream_type (str)

  • eeg_source_id (str | None)

  • marker_stream_types (list[str] | None)

  • special_streams (dict[str, dict] | None)

  • tier2_streams (dict[str, dict] | None)

  • montage (str | DigMontage | None)

  • old_reference (str | None)

  • keep_channels (list[str] | None)

  • drop_channels (list[str] | None)

  • target_sfreq (float | None)

  • alignment_method (Literal['linear', 'pchip', 'sinc', 'nearest', 'stim'])

  • max_nan_gap_s (float | None)

  • on_mismatch (Literal['crop', 'pad'])

Methods

__init__([eeg_stream_name, eeg_stream_type, ...])

load(path)

Load an XDF file and return a MultimodalRecording.
load(path)[source]#

Load an XDF file and return a MultimodalRecording.

Parameters:
pathstr or Path

Path to the XDF file.

Returns:
MultimodalRecording
Parameters:

path (str | Path)

Return type:

MultimodalRecording