How to use a custom dataset with bciflow library

Introduction

This tutorial explains how to correctly create the dataset dictionary required by the kfold function. You can build this dictionary with your own data, as long as it follows the expected structure defined by the library.

Expected Structure of dataset

The dataset is a dictionary with the following fields:

  • X: EEG array with shape (trials, bands, channels, time);

  • y: vector with class labels (one per trial);

  • sfreq: sampling frequency of the EEG signal (in Hz);

  • y_dict: dictionary mapping integer labels to class names;

  • events: dictionary with event markers per trial;

  • ch_names: list of channel names;

  • tmin: time offset relative to the event (in seconds).

Example with Comments

Building the dataset dictionary
import numpy as np
from bciflow.modules.core.kfold import kfold
from bciflow.modules.tf.bandpass.chebyshevII import chebyshevII
from bciflow.modules.fe.logpower import logpower
from sklearn.discriminant_analysis import LinearDiscriminantAnalysis as lda

# === EEG data shaped as (trials, bands, channels, time) ===
X = np.array([])  # Your EEG data must follow this format

# === Label vector (one integer per trial) ===
y = np.array([])

# === Sampling frequency (in Hz) ===
sfreq = float  # Example: 250.0

# === Dictionary mapping labels to class names ===
y_dict = {"class": int, ...}  # Example: {0: "left hand", 1: "right hand"}

# === Dictionary with event timings (in seconds) ===
events = {"Task": float, ...}  # Example: {"cue": [2.0, 2.5, 3.0, ...]}

# === List of EEG channel names ===
ch_names = list  # Example: ['C3', 'Cz', 'C4']

# === Time offset relative to the event ===
tmin = float  # Example: 0.5

# Group all elements into a single dictionary
dataset = {
    'X': X,
    'y': y,
    'sfreq': sfreq,
    'y_dict': y_dict,
    'events': events,
    'ch_names': ch_names,
    'tmin': tmin
}

Next Steps

Once the dataset dictionary is properly created, you are ready to use it directly in the kfold pipeline. This dictionary becomes the main input for the evaluation and processing pipeline, allowing you to apply preprocessing, feature extraction, and classification modules in a structured and repeatable way.

For a more complete example of a typical use case—including filtering, feature extraction, and classification with the FBCSP method—we recommend referring to the introductory tutorial provided with the bciflow library. That tutorial demonstrates how to set up and run a full pipeline from start to finish using sample data and the FBCSP algorithm.