I/O API

I/O processors for loading and exporting EEG data.

Note

GDFExporter and MFFExporter are included for explicit format routing, but currently raise ProcessorValidationError at runtime because MNE does not support writing those formats in the current dependency stack.

Loaders

Loader

class facet.io.Loader(path: str, bad_channels: list[str] | None = None, preload: bool = True, artifact_to_trigger_offset: float = 0.0, upsampling_factor: int = 1, start_sample: int | None = None, stop_sample: int | None = None)

Bases: Processor

Load EEG data with automatic file-format detection.

Inspects the file extension and selects the appropriate MNE reader. Supports EDF, BDF, GDF, BrainVision (.vhdr), EEGLAB (.set), FIF (.fif / .fif.gz), and EGI MFF (.mff). For BIDS datasets use BIDSLoader. Note: MFF format uses a directory structure; pass the path to the .mff directory (e.g. recording.mff).

Parameters:

• path (str) – Path to the EEG data file.

• bad_channels (list of str, optional) – Channel names to mark as bad (default: none).

• preload (bool, optional) – Whether to load data into memory immediately (default: True).

• artifact_to_trigger_offset (float, optional) – Offset of the artifact relative to the trigger, in seconds (default: 0.0).

• upsampling_factor (int, optional) – Upsampling factor stored in metadata for downstream processors (default: 1).

• start_sample (int, optional) – First sample index to keep, inclusive (default: first sample).

• stop_sample (int, optional) – Last sample index to keep, exclusive (default: last sample).

name: str = 'auto_loader'

description: str = 'Load EEG data with automatic format detection'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = False

modifies_raw: bool = True

parallel_safe: bool = False

__init__(path: str, bad_channels: list[str] | None = None, preload: bool = True, artifact_to_trigger_offset: float = 0.0, upsampling_factor: int = 1, start_sample: int | None = None, stop_sample: int | None = None) → None

Initialize processor.

validate(context: ProcessingContext | None) → None

Validate that prerequisites are met.

Override this method to add custom validation logic.

Parameters:

context – Processing context

Raises:

ProcessorValidationError – If validation fails

process(context: ProcessingContext | None) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).

BIDSLoader

class facet.io.BIDSLoader(root: str, subject: str, task: str, session: str | None = None, run: str | None = None, bad_channels: list[str] | None = None, preload: bool = True, artifact_to_trigger_offset: float = 0.0, upsampling_factor: int = 1, start_sample: int | None = None, stop_sample: int | None = None)

Bases: Processor

Load EEG data from a BIDS dataset.

Creates a new ProcessingContext by reading EEG data identified by subject, task, and optional session from a BIDS-compliant directory. Optionally restricts the recording to a sample window and marks a list of channels as bad before returning.

Parameters:

• root (str) – Path to the BIDS root directory.

• subject (str) – Subject identifier (without the sub- prefix).

• task (str) – Task name.

• session (str, optional) – Session identifier (without the ses- prefix).

• run (str, optional) – Run identifier (without the run- prefix).

• bad_channels (list of str, optional) – Channel names to mark as bad (default: none).

• preload (bool, optional) – Whether to load data into memory immediately (default: True).

• artifact_to_trigger_offset (float, optional) – Offset of the artifact relative to the trigger, in seconds (default: 0.0).

• upsampling_factor (int, optional) – Upsampling factor stored in metadata for downstream processors (default: 1).

• start_sample (int, optional) – First sample index to keep, inclusive (default: first sample).

• stop_sample (int, optional) – Last sample index to keep, exclusive (default: last sample).

name: str = 'bids_loader'

description: str = 'Load EEG data from BIDS dataset'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = False

modifies_raw: bool = True

parallel_safe: bool = False

__init__(root: str, subject: str, task: str, session: str | None = None, run: str | None = None, bad_channels: list[str] | None = None, preload: bool = True, artifact_to_trigger_offset: float = 0.0, upsampling_factor: int = 1, start_sample: int | None = None, stop_sample: int | None = None) → None

Initialize processor.

validate(context: ProcessingContext | None) → None

Validate that prerequisites are met.

Override this method to add custom validation logic.

Parameters:

context – Processing context

Raises:

ProcessorValidationError – If validation fails

process(context: ProcessingContext | None) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).

Exporters

Exporter

class facet.io.Exporter(path: str, overwrite: bool = True)

Bases: Processor

Export EEG data with automatic file-format routing.

Routes export requests to the file-type-specific exporter based on the destination extension.

Parameters:

• path (str) – Destination path; extension determines exporter selection.

• overwrite (bool, optional) – Whether to overwrite existing outputs (default: True).

name: str = 'auto_exporter'

description: str = 'Export EEG data with automatic format detection'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = True

modifies_raw: bool = False

parallel_safe: bool = False

__init__(path: str, overwrite: bool = True) → None

Initialize processor.

validate(context: ProcessingContext) → None

Validate that prerequisites are met.

Override this method to add custom validation logic.

Parameters:

context – Processing context

Raises:

ProcessorValidationError – If validation fails

process(context: ProcessingContext) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).

EDFExporter

class facet.io.EDFExporter(path: str, overwrite: bool = True)

Bases: Processor

Export EEG data to EDF format.

Writes the current Raw object to an EDF file at the specified path. Parent directories are created automatically if they do not exist. The context is returned unchanged; only the file is written.

Parameters:

• path (str) – Destination file path for the exported EDF.

• overwrite (bool, optional) – Whether to overwrite an existing file (default: True).

name: str = 'edf_exporter'

description: str = 'Export EEG data to EDF file'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = True

modifies_raw: bool = False

parallel_safe: bool = False

__init__(path: str, overwrite: bool = True) → None

Initialize processor.

process(context: ProcessingContext) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).

BDFExporter

class facet.io.BDFExporter(path: str, overwrite: bool = True)

Bases: Processor

Export EEG data to BDF format.

Parameters:

• path (str) – Destination file path for the exported BDF.

• overwrite (bool, optional) – Whether to overwrite an existing file (default: True).

name: str = 'bdf_exporter'

description: str = 'Export EEG data to BDF file'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = True

modifies_raw: bool = False

parallel_safe: bool = False

__init__(path: str, overwrite: bool = True) → None

Initialize processor.

process(context: ProcessingContext) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).

BrainVisionExporter

class facet.io.BrainVisionExporter(path: str, overwrite: bool = True)

Bases: Processor

Export EEG data to BrainVision format.

Parameters:

• path (str) – Destination BrainVision header path (.vhdr).

• overwrite (bool, optional) – Whether to overwrite an existing file set (default: True).

name: str = 'brainvision_exporter'

description: str = 'Export EEG data to BrainVision file set'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = True

modifies_raw: bool = False

parallel_safe: bool = False

__init__(path: str, overwrite: bool = True) → None

Initialize processor.

process(context: ProcessingContext) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).

EEGLABExporter

class facet.io.EEGLABExporter(path: str, overwrite: bool = True)

Bases: Processor

Export EEG data to MATLAB EEGLAB format.

Parameters:

• path (str) – Destination file path for the exported EEGLAB .set file.

• overwrite (bool, optional) – Whether to overwrite an existing file (default: True).

name: str = 'eeglab_exporter'

description: str = 'Export EEG data to MATLAB EEGLAB file'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = True

modifies_raw: bool = False

parallel_safe: bool = False

__init__(path: str, overwrite: bool = True) → None

Initialize processor.

process(context: ProcessingContext) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).

FIFExporter

class facet.io.FIFExporter(path: str, overwrite: bool = True)

Bases: Processor

Export EEG data to FIF format.

Parameters:

• path (str) – Destination file path for the exported FIF file (.fif or .fif.gz).

• overwrite (bool, optional) – Whether to overwrite an existing file (default: True).

name: str = 'fif_exporter'

description: str = 'Export EEG data to FIF file'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = True

modifies_raw: bool = False

parallel_safe: bool = False

__init__(path: str, overwrite: bool = True) → None

Initialize processor.

process(context: ProcessingContext) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).

GDFExporter

class facet.io.GDFExporter(path: str, overwrite: bool = True)

Bases: Processor

Route target for GDF exports.

MNE currently does not provide GDF writing support.

name: str = 'gdf_exporter'

description: str = 'Export EEG data to GDF file (unsupported in current runtime)'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = True

modifies_raw: bool = False

parallel_safe: bool = False

__init__(path: str, overwrite: bool = True) → None

Initialize processor.

validate(context: ProcessingContext) → None

Validate that prerequisites are met.

Override this method to add custom validation logic.

Parameters:

context – Processing context

Raises:

ProcessorValidationError – If validation fails

process(context: ProcessingContext) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).

MFFExporter

class facet.io.MFFExporter(path: str, overwrite: bool = True)

Bases: Processor

Route target for EGI MFF exports.

MNE currently does not provide MFF writing support.

name: str = 'mff_exporter'

description: str = 'Export EEG data to MFF directory (unsupported in current runtime)'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = True

modifies_raw: bool = False

parallel_safe: bool = False

__init__(path: str, overwrite: bool = True) → None

Initialize processor.

validate(context: ProcessingContext) → None

Validate that prerequisites are met.

Override this method to add custom validation logic.

Parameters:

context – Processing context

Raises:

ProcessorValidationError – If validation fails

process(context: ProcessingContext) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).

BIDSExporter

class facet.io.BIDSExporter(root: str, subject: str, task: str, session: str | None = None, event_id: dict | None = None, overwrite: bool = True)

Bases: Processor

Export EEG data to BIDS format.

Writes the current Raw object into a BIDS-compliant directory structure using MNE-BIDS. Stimulus channels are dropped before writing as per BIDS convention. If triggers are available in the context they are written as events. Parent directories are created automatically.

Parameters:

• root (str) – Path to the BIDS root directory.

• subject (str) – Subject identifier (without the sub- prefix).

• task (str) – Task name.

• session (str, optional) – Session identifier (without the ses- prefix).

• event_id (dict, optional) – Mapping of event description strings to integer event codes.

• overwrite (bool, optional) – Whether to overwrite existing BIDS files (default: True).

name: str = 'bids_exporter'

description: str = 'Export EEG data to BIDS dataset'

version: str = '1.0.0'

requires_triggers: bool = False

requires_raw: bool = True

modifies_raw: bool = False

parallel_safe: bool = False

__init__(root: str, subject: str, task: str, session: str | None = None, event_id: dict | None = None, overwrite: bool = True) → None

Initialize processor.

process(context: ProcessingContext) → ProcessingContext

Process the context.

This is the main method to implement in subclasses.

Parameters:

context – Input processing context

Returns:

Output processing context. If None is returned, the input context is used (no-op behavior).