Datasets¶

Built-in dataset initialization¶

Benchmark Dataset¶

This dataset gathered SSVEP-BCI recordings of 35 healthy subjects (17 females, aged 17-34 years, mean age: 22 years) focusing on 40 characters flickering at different frequencies (8-15.8 Hz with an interval of 0.2 Hz).

For each subject, the experiment consisted of 6 blocks. Each block contained 40 trials corresponding to all 40 characters indicated in a random order. Each trial started with a visual cue (a red square) indicating a target stimulus. The cue appeared for 0.5 s on the screen.

Following the cue offset, all stimuli started to flicker on the screen concurrently and lasted 5 s.

After stimulus offset, the screen was blank for 0.5 s before the next trial began, which allowed the subjects to have short breaks between consecutive trials. Each trial lasted a total of 6 s.

SSVEPAnalysisToolbox.datasets.BenchmarkDataset()¶

Initialize the benchmark dataset.

Num. of Subjects	35
Num. of Targets	40
Num. of Channels	64
Num. of Blocks	6
Num. of trials in each blcok	40
Pre-stimulus Time	0.5 s
Break Time	0.5 s
Whole Trial Length	6 s
Default Latency Time	0.14 s
Sampling rate	250 Hz

Total: around 3.45 GB.

Paper: Y. Wang, X. Chen, X. Gao, and S. Gao, “A benchmark dataset for SSVEP-based braincomputer interfaces,” IEEE Trans. Neural Syst. Rehabil. Eng., vol. 25, no. 10, pp. 17461752, 2017. DOI: 10.1109/TNSRE.2016.2627556.

URL: http://bci.med.tsinghua.edu.cn/.

Parameters

path –
Path of storing EEG data.

The missing subjects’ data files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is a folder Benchmark Dataset in the working path.
path_support_file –
Path of supported files, i.e., Readme.txt, Sub_info.txt, 64-channels.loc, and Freq_Phase.mat.

The missing supported files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is same as data path path.

BETA Dataset¶

EEG data after preprocessing are store as a 4-way tensor, with a dimension of channel x time point x block x condition.

Each trial comprises 0.5-s data before the event onset and 0.5-s data after the time window of 2 s or 3 s.

For S1-S15, the time window is 2 s and the trial length is 3 s, whereas for S16-S70 the time window is 3 s and the trial length is 4 s.

Additional details about the channel and condition information can be found in the supplementary information.

SSVEPAnalysisToolbox.datasets.BETADataset()¶

Initialize the BETA dataset.

Num. of Subjects	70
Num. of Targets	40
Num. of Channels	64
Num. of Blocks	4
Num. of trials in each blcok	40
Pre-stimulus Time	0.5 s
Break Time	0.5 s
Whole Trial Length	2 s
Default Latency Time	0.13 s
Sampling rate	250 Hz

Total: around 4.91 GB.

Paper: B. Liu, X. Huang, Y. Wang, X. Chen, and X. Gao, “BETA: A large benchmark database toward SSVEP-BCI application,” Front. Neurosci., vol. 14, p. 627, 2020. DOI: 10.3389/fnins.2020.00627.

URL: http://bci.med.tsinghua.edu.cn/.

Parameters

path –
Path of storing EEG data.

The missing subjects’ data files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is a folder BETA Dataset in the working path.
path_support_file –
Path of supported files, i.e., note.pdf, and description.pdf.

The missing supported files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is same as data path path.

Nakanishi 2015 Dataset¶

Each .mat file has a four-way tensor electroencephalogram (EEG) data for each subject. Please see the reference paper for the detail.

size(eeg) = [Num. of targets, Num. of channels, Num. of sampling points, Num. of trials]

The order of the stimulus frequencies in the EEG data: [9.25, 11.25, 13.25, 9.75, 11.75, 13.75, 10.25, 12.25, 14.25, 10.75, 12.75, 14.75] Hz (e.g., eeg(1,:,:,:) and eeg(5,:,:,:) are the EEG data while a subject was gazing at the visual stimuli flickering at 9.25 Hz and 11.75Hz, respectively.)
The onset of visual stimulation is at 39th sample point.

SSVEPAnalysisToolbox.datasets.NakanishiDataset()¶

Initialize the Nakanishi2015 dataset.

Num. of Subjects	10
Num. of Targets	12
Num. of Channels	8
Num. of Blocks	15
Num. of trials in each blcok	12
Pre-stimulus Time	0.1523 (39/256) s
Break Time	1 s
Whole Trial Length	4.3516 (1114/256) s
Default Latency Time	0.135 s
Sampling rate	256 Hz

Total: around 148 MB.

Paper: M. Nakanishi, Y. Wang, Y.-T. Wang, T.-P. Jung, “A Comparison Study of Canonical Correlation Analysis Based Methods for Detecting Steady-State Visual Evoked Potentials,” PLoS ONE, vol. 10, p. e0140703, 2015. DOI: 10.1371/journal.pone.0140703.

URL: ftp://sccn.ucsd.edu/pub/cca_ssvep.zip <ftp://sccn.ucsd.edu/pub/cca_ssvep.zip.

Parameters

path –

Path of storing EEG data.

The missing subjects’ data files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is a folder Nakanishi2015 Dataset in the working path.

eldBETA Dataset¶

For the BCI users, there was an associated epoched record that is stored in “.mat” structure array from MATLAB.

The structure array in each record was composed of the EEG data (“EEG”) and its associated supplementary information (“Suppl_info”) as its fields. In the “EEG” field of the record, two types of EEG data, i.e., EEG epochs and raw EEG were provided for researchers to facilitate diverse research purposes.

The EEG epochs were the EEG data with the data processing and stored as 4-dimensional matrices (channel x time point x condition x block). The names and locations of the channel dimension were given in the supplementary information.

For the dimension of time point, the epochs had a length of 6 s, which included 0.5 s before the stimulus onset, 5 s during the stimulation (SSVEPs) and 0.5 s after the stimulus offset.

Different from the epoched data, the raw EEG provided continuous EEG that were converted by EEGLAB. The raw EEG were stored as cell arrays, each of which contained a block of EEG data. The “Suppl_info” field of the record provided a basic information about personal statistics and experimental protocol. The personal statistics included the aged, gender, BCIQ and SNR with respect to each subject. The experimental protocol included channel location (“Channel), stimulus frequency (“Frequency”), stimulus initial phase (“Phase”) and sampling rate (“Srate”). The channel location was represented by a 64x4 cell arrays. The first column and the fourth column denoted the channel index and channel name, respectively. The second column and the third column denoted the channel location in polar coordinates, i.e., degree and radius, respectively. The stimulus initial phase was given in radius. The sampling rate of the epoch data was denoted by “Srate”.

SSVEPAnalysisToolbox.datasets.ELDBETADataset()¶

Initialize the eldBETA dataset.

Num. of Subjects	100
Num. of Targets	9
Num. of Channels	64
Num. of Blocks	7
Num. of trials in each blcok	9
Pre-stimulus Time	0.5 s
Break Time	0.5 s
Whole Trial Length	6 s
Default Latency Time	0.14 s
Sampling rate	250 Hz

Total: around 20.0 GB

Paper: B. Liu, Y. Wang, X. Gao, and X. Chen, “eldBETA: A Large eldercare-oriented benchmark database of SSVEP-BCI for the aging population,” Scientific Data, vol. 9, no. 1, pp.1-12, 2022. DOI: 10.1038/s41597-022-01372-9.

URL: http://bci.med.tsinghua.edu.cn/.

Parameters

path –
Path of storing EEG data.

The missing subjects’ data files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is a folder BETA Dataset in the working path.
path_support_file –
Path of supported files, i.e., note.pdf, and description.pdf.

The missing supported files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is same as data path path.

openBMI Dataset¶

Fifty-four healthy subjects (ages 24-35, 25 females) participated in the experiment. Thirty-eight subjects were naive BCI users. The others had previous experience with BCI experiments. None of the participants had a history of neurological, psychiatric, or any other pertinent disease that otherwise might have affected the experimental results.

EEG signals were recorded with a sampling rate of 1000 Hz and collected with 62 Ag/AgCl electrodes.

Four target SSVEP stimuli were designed to flicker at 5.45, 6.67, 8.57, and 12 Hz and were presented in four positions (down, right, left, and up, respectively) on a monitor. The designed paradigm followed the conventional types of SSVEP-based BCI systems that require four-direction movements. Participants were asked to fixate the center of a black screen and then to gaze in the direction where the target stimulus was highlighted in a different color. Each SSVEP stimulus was presented for 4 s with an ISI of 6 s. Each target frequency was presented 25 times. Therefore, the corrected EEG data had 100 trials (4 classes × 25 trials) in the offline training phase and another 100 trials in the online test phase. Visual feedback was presented in the test phase; the estimated target frequency was highlighted for one second with a red border at the end of each trial.

SSVEPAnalysisToolbox.datasets.openBMIDataset()¶

Initialize the openBMI dataset.

Num. of Subjects	54
Num. of Targets	4
Num. of Channels	62
Num. of Blocks	4 (2 sessions * (online part + offline part))
Num. of trials in each blcok	100
Pre-stimulus Time	0 s
Break Time	0 s
Whole Trial Length	4 s
Default Latency Time	0 s
Sampling rate	1000 Hz

Total: around 55.6 GB

Paper: M.-H. Lee, O.-Y. Kwon, Y.-J. Kim, H.-K. Kim, Y.-E. Lee, J. Williamson, S. Fazli, and S.-W. Lee, “EEG dataset and OpenBMI toolbox for three BCI paradigms: An investigation into BCI illiteracy,” GigaScience, vol. 8, no. 5, p. giz002, 2019. DOI: 10.1093/gigascience/giz002.

Data: M. Lee, O. Kwon, Y. Kim, H. Kim, Y. Lee, J. Williamson, S. Fazli, S. Lee, “Supporting data for ‘EEG Dataset and OpenBMI Toolbox for Three BCI Paradigms: An Investigation into BCI Illiteracy’,” GigaScience Database, 2019. DOI: 10.5524/100542.

URL: ftp://ftp.cngb.org/pub/gigadb/pub/10.5524/100001_101000/100542/.

Parameters

path –
Path of storing EEG data.

The missing subjects’ data files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is a folder BETA Dataset in the working path.
path_support_file –
Path of supported files, i.e., note.pdf, and description.pdf.

The missing supported files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is same as data path path.

Wearable SSVEP Dataset¶

This dataset relied on the BCI Brain-Controlled Robot Contest at the 2020 World Robot Contest to recruit participants.

One hundred and two healthy subjects (64 males and 38 females, with an average age of 30.03 ± 0.79 years ranging from 8 to 52 years) with normal or corrected-to-normal eyesight participated in the experiment. total, 53 subjects wore the dry-electrode headband first and 49 subjects wore the wet-electrode headband first.

This research designed an online BCI system with a 12-target speller as a virtual keypad of a phone.

An 8-channel NeuSenW (Neuracle, Ltd. Changzhou, China) wireless EEG acquisition system was used to record the SSVEPs in this study.

Each block included 12 trials, and each trial corresponded to each target.

EEG data were recorded using Neuracle EEG Recorder NeuSen W (Neuracle, Ltd.), a wireless EEG acquisition system with a sampling rate of 1000 Hz. Eight electrodes (POz, PO3, PO4, PO5, PO6, Oz, O1 and O2, sorted by channel index in the dataset) were placed at the parietal and occipital regions on the basis of the international 10 to 20 system to record SSVEPs and two electrodes were placed at the forehead as the reference and ground, respectively.

In accordance with the stimulus onsets recorded in the event channel of the continuous EEG data, data epochs could be extracted. The length of each data epoch was 2.84 s, including 0.5 s before the stimulus onset, 0.14 s for visual response delay, 2 s for stimulus, and 0.2 s after stimulus. With the purpose of reducing the storage and computation costs, all data were down sampled to 250 Hz.

The electrode impedances recorded before each block were provided in the data matrix of ‘Impedance.mat’ with dimensions of [8, 10, 2, 102]. The channel index are corresponding to POz, PO3, PO4, PO5, PO6, Oz, O1, O2. The numbers in the four dimensions represent the number of channels, blocks, headband types (1: wet, 2: dry) and subjects respectively. The impedance information can be used to study the relationship be tween impedance and BCI performance.

The “Subjects_information.mat” file lists the information of all 102 subjects together with aquestionnaire on the comfort level and preference of the two headbands after the experiment. For each participant, there are 10 columns of parameters (factors). The first 4 colu mns are the subjects’ personal information including “subject index”, “gender”, “age”, and “dominant hand”. The 6 columns(5th 10th) are listed as results in questionnaires, which are “Comfort of dry electrode headband”, “Wearing time of dry electrode when pain occurs”, “Comfort of wet electrode headband”, “Wearing time of wet electrode when pain occurs”, “Only consider comfort, headband preference” and “comprehensively consider comfort and convenience (need assistance from others, conductive paste, shampoo, etc.), headband preference”. The last column shows the order of wearing the two headbands.

The “stimulation_information.pdf” file lists the stimulation parameters of the 12 characters, including frequency and phase information of each character.

SSVEPAnalysisToolbox.datasets.WearableDataset_wet()¶

Initialize the wearable dataset (wet electrodes).

Num. of Subjects	102
Num. of Targets	12
Num. of Channels	8
Num. of Blocks	10
Num. of trials in each blcok	12
Pre-stimulus Time	0.5 s
Break Time	0.2 s
Whole Trial Length	2.84 s
Default Latency Time	0.14 s
Sampling rate	250 Hz

Total: around 929 MB

Paper: F. Zhu, L. Jiang, G. Dong, X. Gao, and Y. Wang, “An Open Dataset for Wearable SSVEP-Based Brain-Computer Interfaces,” Sensors, vol. 21, no. 4, p. 1256, 2021. DOI: 10.3390/s21041256.

URL: http://bci.med.tsinghua.edu.cn/..

Parameters

path –
Path of storing EEG data.

The missing subjects’ data files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is a folder BETA Dataset in the working path.
path_support_file –
Path of supported files, i.e., note.pdf, and description.pdf.

The missing supported files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is same as data path path.

SSVEPAnalysisToolbox.datasets.WearableDataset_dry()¶

Initialize the wearable dataset (dry electrodes).

Num. of Subjects	102
Num. of Targets	12
Num. of Channels	8
Num. of Blocks	10
Num. of trials in each blcok	12
Pre-stimulus Time	0.5 s
Break Time	0.2 s
Whole Trial Length	2.84 s
Default Latency Time	0.14 s
Sampling rate	250 Hz

Total: around 929 MB

Paper: F. Zhu, L. Jiang, G. Dong, X. Gao, and Y. Wang, “An Open Dataset for Wearable SSVEP-Based Brain-Computer Interfaces,” Sensors, vol. 21, no. 4, p. 1256, 2021. DOI: 10.3390/s21041256.

URL: http://bci.med.tsinghua.edu.cn/..

Parameters

path –
Path of storing EEG data.

The missing subjects’ data files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is a folder BETA Dataset in the working path.
path_support_file –
Path of supported files, i.e., note.pdf, and description.pdf.

The missing supported files will be downloaded when the dataset is initialized.

If the provided path is not existed, the provided path will be created.

Default path is same as data path path.

Attributes of datasets¶

All datasets have these attributes. Attributes in different datasets have different values.

subjects

A list of subject information. Each element is a SubInfo instance, which contains following attributes:

ID: Unique identifier of subject.
path: Path of corresponding EEG data file.
name: Name of subject.
age: Age of subject.
gender: Gender of subject. M for male. F for female.

ID

Name/ID of the dataset.

url

Download URL.

paths

A list of EEG data path. Each subject has a individual data path.

channels

A list of channel names

srate

Sampling rate (Hz)

block_num

Number of blocks

trial_num

Number of trials in each block

trial_len

Signal length (in second) of single trial. If different trials have different siganl length, the shorted signal length is stored.

stim_info

A dictionary storing stimulus information, which contains following keys:

stim_num: Number of stimuli.
freqs: A list of stimulus frequencies.
phases: A list of stimulus phases.

t_prestim

Pre-stimulus time (in second).

t_break

Time for shifting visual attention (in second).

support_files

A list of supported files.

path_support_file

Path of supported files

default_t_latency

Default/suggested latency time (in second).

Methods of datasets¶

For all datasets, the toolbox will the unified APIs to hook the proprocessing and filterbank functions and output signals. The unified APIs are listed here:

download_all()¶: Download all subjects’ data file. Because all data files will be donwloaded automatically when a dataset is initialized, this function normally does not need to be run manually.

download_support_files()¶: Download all supported files. Because all supported files will be downloaded automatically when a dataset is initialized, this function normally does not need to be run manually.

reset_preprocess()¶: Set the preprocess function as the default preprocess function. The default preprocess function is empty. It will directly return the original EEG signals without any preprocessing.

regist_preprocess()¶

Hook the user-defined preprocessing function.

Parameters: preprocess_fun – User-defined preprocessing function.

Note

The given preprocess_fun should be a callable function name (only name). This callable function should only have two input parameter dataself and X.

dataself is the data istance. If you need to use parameters in the data module, you can directly use them from dataself.
X is a 2D EEG signal (channels × samples). The pre-stimulus time has been removed from the EEG signal. The latency time is maintained in the EEG signal. The detailed data extraction procedures please refer to “get_data” function.

If your preprocess function needs other input parameters, you may use lambda function. Check demos to get more hints.

You may refer the following default preprocess function to define your own function.

def default_preprocess(dataself, X: ndarray) -> ndarray:
    return X

reset_filterbank()¶: Set the filterbank function as the default filterbank function. In the default filterbank function, the original EEG signals will be considered as one filterbank. If the original EEG signal is a 2D signal (channels × samples), one more dimention will be expanded (filterbank × channels × samples). If the original EEG signal is a 3D signal, original signal will be returned without any processing.

regist_filterbank()¶

Hook the user-defined filterbank function.

Parameters: filterbank_fun – User-defined filterbank function.

Note

The given filterbank_fun should be a callable function name (only name). This callable function should only have two input parameter dataself and X.

dataself is the data istance. If you need to use parameters in the data module, you can directly use them from dataself.
X is a 2D EEG signal (channels × samples). The pre-stimulus time has been removed from the EEG signal. The latency time is maintained in the EEG signal. The detailed data extraction procedures please refer to “get_data” function.

The output of the given filterbank_fun should be a 3D EEG signal (filterbank × channels × samples). The bandpass filtered EEG signals of filterbanks should be stored in the first dimension.

If your filterbank function needs other input parameters, you may use lambda function. Check demos to get more hints.

You may refer the following default preprocess function to define your own function.

def default_filterbank(dataself, X: ndarray) -> ndarray:
    """
    default filterbank (1 filterbank contains original signal)
    """
    if len(X.shape) == 2:
        return expand_dims(X,0)
    elif len(X.shape) == 3:
        return X
    else:
        raise ValueError("The shapes of EEG signals are not correct")

leave_one_block_out()¶

According to the given testing block index, generate lists of testing and training block indices following the leave-one-block-out rule.

Tip

Leave-one-block-out rule: One block works as the testing block. All other blocks work as the training blocks.

Parameters

block_idx – Given testing block index.

Returns

test_block: List of one testing block index
train_block: List of training block indices

get_data()¶

Extract EEG signals and corresponding labels from the dataset

Parameters

sub_idx – Subject index.
blocks – List of block indices.
trials – List of trial indices.
channels – List of channel indices.
sig_len – Signal length (in second).
t_latency – Latency time (in second). Default is the default/suggested latency time of the dataset.
shuffle – If True, the order of trials will be shuffled. Otherwise, the order of trials will follow the given blocks and trials.

Returns

X: List of single trial EEG signals.
Y: List of labels.

Note

The preprocess and filterbanks are applied to windowed signals (not whole trial signal), which is close to the real online situation. The extraction will follow these steps:

Cut the signal according to given sig_len. The pre-stimulus time t_prestim will be removed. The latency time is maintained.
Apply the hooked preprocessing function.
Apply the bandpass filters of filterbanks.
Remove the latency time.

The extraction process follows the below figure.

get_data_all_trials()¶

Extract EEG signals of all trials in given blocks and corresponding labels from the dataset. This function is similar as get_data but it does not need trials and will extract all trials of given blocks.

Parameters

sub_idx – Subject index.
blocks – List of block indices.
channels – List of channel indices.
sig_len – Signal length (in second).
t_latency – Latency time (in second). Default is the default/suggested latency time of the dataset.
shuffle – If True, the order of trials will be shuffled. Otherwise, the order of trials will follow the given blocks and trials.

Returns

X: List of single trial EEG signals.
Y: List of labels.

reset_ref_sig_fun()¶

Set the reference signal generation function as the default sine-cosine reference generation function. The default sine-cosine reference generation function uses the sampling frequency of the original signal (recoded in the dataset) to generate the reference signals. The reference signals of \(i\text{-th}\) stimulus can be presented as

\[\begin{split}\mathbf{Y}_i(t) = \left[ \begin{array}{c} \sin(2\pi f_i t + \theta_i)\\ \cos(2\pi f_i t + \theta_i)\\ \vdots\\ \sin(2\pi N_h f_i t + N_h \theta_i)\\ \cos(2\pi N_h f_i t + N_h \theta_i) \end{array} \right]\end{split}\]

where \(f_i\) and \(\theta_i\) denote the stimulus frequency and phase of the \(i\text{-th}\) stimulus, and \(N_h\) denotes the total number of harmonic components.

regist_ref_sig_fun()¶

Hook the user-defined reference generation function.

Parameters: ref_sig_fun – User-defined reference generation function.

Note

The given preprocess_fun should be a callable function name (only name). This callable function should only have four input parameter:

dataself is the data istance. If you need to use parameters in the data module, you can directly use them from dataself.
sig_len is the signal length (in second).
N is the total number of harmonic components.
phases is the phases of stimuli.

The frequencies of stimuli can be obtained from dataself.

If your reference generation function needs other input parameters, you may use lambda function. Check demos to get more hints.

Normally, you do not need to define your own reference signal generation function. But, when you change the sampling rate (upsampling or downsampling in the preprocess), you must define your own reference signal generation function using the new sampling rate. You may refer the following default reference signal generation function to define your own function.

def default_ref_sig_fun(dataself, sig_len: float, N: int, phases: List[float]):
    L = floor(sig_len * dataself.srate)
    ref_sig = [gen_ref_sin(freq, dataself.srate, L, N, phase) for freq, phase in zip(dataself.stim_info['freqs'], phases)]
    return ref_sig

Tip

gen_ref_sin is in Computation functions.

get_ref_sig()¶

Generate sine-cosine-based reference signals by using the registed reference generation function.

Parameters

sig_len – Signal length (in second). It should be same as the signal length of extracted EEG signals.
N – Total number of harmonic components.
ignore_stim_phase – If True, all stimulus phases will be set as 0. Otherwise, the stimulus phases stored in the dataset will be applied.

Returns

ref_sig: List of reference signals. Each stimulus have one set of reference signals.

get_snr_single_trial()¶

Calculate SNR of one specific single trial

Parameters

sub_idx – Subject index.
block_idx – Block index.
trial_idx – Trial index.
ch_idx – Channel index.
sig_len – Signal length (in second).
filter_bank_idx – Filterbank index. Default is 0, which will calculate the SNR of signals obtained from the first filter.
Nh – Number of harmonics if use the FFT to calculate the SNR. Default is 1.
srate – Sampling frequency (Hz). Default is None, which will use the sampling freqency of the dataset.
t_latency – Latency time (in second). Default is None, which will use the default latency time of the dataset.
detrend_flag – If use the FFT to calculate the SNR, whether detrend the signal before the FFT. Default is True.
NFFT – Number of the FFT if use the FFT to calculate the SNR. Default is None, which will use the signal length.
type –
Method of calculating the FFT. Default is 'fft'. Supported methods:
- 'fft': Use the FFT to calculate spectrum of the signal, and then calculate the SNR.
- 'sine': Use the sine-cosine reference signal to calculate the SNR.
harmonic_num – Number of harmonic if use the sine-cosine reference signal to calculate the SNR.
ignore_stim_phase – Whether ignore the stimulus phase of generating the reference signals if use the sine-cosine reference signal to calculate the SNR.

Returns

snr: SNR of the specific single trial.

get_snr()¶

Calculate SNRs of all trials

Parameters

filter_bank_idx – Filterbank index. Default is 0, which will calculate the SNR of signals obtained from the first filter.
Nh – Number of harmonics if use the FFT to calculate the SNR. Default is 1.
srate – Sampling frequency (Hz). Default is None, which will use the sampling freqency of the dataset.
t_latency – Latency time (in second). Default is None, which will use the default latency time of the dataset.
remove_break – Whether remove the break time. Default is True.
remove_pre_and_latency – Whether remove pre-stimulus and latency time. Default is True.
display_progress – Whether display the progress bar. Default is False.
detrend_flag – If use the FFT to calculate the SNR, whether detrend the signal before the FFT. Default is True.
NFFT – Number of the FFT if use the FFT to calculate the SNR. Default is None, which will use the signal length.
sig_len – Signal length (in second).
type –
Method of calculating the FFT. Default is 'fft'. Supported methods:
- 'fft': Use the FFT to calculate spectrum of the signal, and then calculate the SNR.
- 'sine': Use the sine-cosine reference signal to calculate the SNR.
harmonic_num – Number of harmonic if use the sine-cosine reference signal to calculate the SNR.
ignore_stim_phase – Whether ignore the stimulus phase of generating the reference signals if use the sine-cosine reference signal to calculate the SNR.
ch_used_recog – List of channel indices if use the sine-cosine reference signal to calculate the SNR.

Returns

snr: SNRs of all trials. If type is fft, the shape is (subjects × blocks × trials × channels). If type is sine, the shape is (subjects × blocks × trials).

get_phase_single_trial()¶

Calculate phases of SSVEP signals in one specific single trial

Parameters

sub_idx – Subject index.
block_idx – Block index.
trial_idx – Trial index.
ch_idx – Channel index.
sig_len – Signal length (in second).
filter_bank_idx – Filterbank index. Default is 0, which will calculate the SNR of signals obtained from the first filter.
srate – Sampling frequency (Hz). Default is None, which will use the sampling freqency of the dataset.
t_latency – Latency time (in second). Default is None, which will use the default latency time of the dataset.
detrend_flag – If use the FFT to calculate the SNR, whether detrend the signal before the FFT. Default is True.
NFFT – Number of the FFT if use the FFT to calculate the SNR. Default is None, which will use the signal length.
remove_target_phase – Whether remove the stimulus phase recorded in the dataset.

Returns

phase: Phase of the specific single trial.

get_phase()¶

Calculate phases of SSVEP signals in all trials

Parameters

filter_bank_idx – Filterbank index. Default is 0, which will calculate the SNR of signals obtained from the first filter.
srate – Sampling frequency (Hz). Default is None, which will use the sampling freqency of the dataset.
t_latency – Latency time (in second). Default is None, which will use the default latency time of the dataset.
remove_break – Whether remove the break time. Default is True.
remove_pre_and_latency – Whether remove pre-stimulus and latency time. Default is True.
display_progress – Whether display the progress bar. Default is False.
detrend_flag – If use the FFT to calculate the SNR, whether detrend the signal before the FFT. Default is True.
NFFT – Number of the FFT if use the FFT to calculate the SNR. Default is None, which will use the signal length.
sig_len – Signal length (in second).
remove_target_phase – Whether minus the stimulus phase recorded in the dataset.

Returns

phase: Phases of all trials. The shape is (subjects × blocks × trials × channels).

How to define your own dataset class¶

You can use the abstract class SSVEPAnalysisToolbox.datasets.BaseDataset as the father class to define your own dataset class. In your own dataset class, the following functions should be defined:

__init__: Except path and path_support_file, other attributes mentioned in Section “Attributes of datasets” normally have been defined in the dataset. Therefore, the initialization function should be re-defined. You may ask for __init__ of the father class SSVEPAnalysisToolbox.datasets.BaseDataset to store these attributes in class.
Following abstract functions in SSVEPAnalysisToolbox.datasets.BaseDataset are empty and should be defined in your own dataset class:

download_single_subject()¶

Donwload one subject’s data file.

Parameters

subject –
One SubInfo instance stored in subjects mentioned in Section “Attributes of datasets”.

download_file()¶

Download one supported file.

Parameters

file_name – File name that will be downloaded.

Tip

You may use “download_single_file” function to download the required file. You also may need “tarfile” or “py7zr” to uncompress data files.
get_sub_data()¶
Read one subject data from the local data file.
Parameters

sub_idx – Subject index.

Returns
data: The provided data should be a 4D data (blocks × trials × channels × samples). Each trial should contain the whole trial data including pre-stimulus time, and latency time.
Note

The data provided by “get_sub_data” function must be 4D. The order of dimentions should be exactly (blocks × trials × channels × samples).
get_label_single_trial()¶
Generate the label of one specific trial.
Parameters
sub_idx – Subject index.

block_idx – Block index.

stim_idx – Trial index.
Returns
label: Label of the specific trial. The label should be one integer number.
According to your requirements, you may re-define existed functions listed in Functions of datasets.