APPEAR Toolbox

An Automatic Pipeline for EEG Artifact Reduction

Code co-main author, developer and maintainer is: Obada Al Zoubi

If you have any questions, please reach out to me at my email: obada.y.alzoubi@gmail.com

Also, check my website for more infomration about me [www.obadaalzoubi.com]

Why APPEAR Toolbox ?

Removing artifacts from simultaneous EEG-fMRI recordings is a challenging issue since it requires manual attending with specialized expertise. Additionally, manual correction is prone to experimenter biases in cleaning data. Thus, we developed a fully automated pipeline for EEG artifacts reduction (APPEAR). APPEAR was validated and compared to manual EEG preprocessing for two common applications - resting and task-based EEG-fMRI acquisitions. APPEAR offers A-to-Z preprocessing for EEG and generates ready-to-analyze output while cleaning MR, ballistocardiogram (BCG), pulse, eye blinking, saccades, muscles, and single-channel artifacts. This is achieved by following well-validated steps using signal processing and Independent Component Analysis (ICA).
Also, APPEAR can be used to process large scale datasets while supporting parallel implementations. In this technical report, we provide a detailed explanation of using the toolbox while highlighting the important technical details for the user. APPEAR is implemented using MATLAB software with dependencies on EEGLAB (Delorme & Makeig, 2004) and fMRIb (Niazy, Beckmann, Iannetti, Brady, & Smith, 2005) toolboxes.
I elaborate on several parameters that are used in the APPEAR toolbox using demo examples. Additionally, I provide information about several functions and features offered with the APPEAR toolbox.

Please refer to Ahmad Mayeli*, Obada Al Zoubi* et al 2021 J. Neural Eng. 18 0460b4 for in-depth analysis and scientific validation of the pipeline

Fig1 [source: Ahmad Mayeli, Obada Al Zoubi et al 2021 J. Neural Eng. 18 0460b4]

Installation

Requirements

Please use MATLAB 2018 or later to ensure that the APPEAR toolbox is working correctly. Also, please use the attached version of EEGLAB with the APPEAR toolbox. It is possible to use later versions of MATLAB and EEGLAB; however, for EEGLAB, you need to install the required plug-in like fMRIb. MATLAB 2018 or later
EEGLAB 2019 or later
fMRIb \

Software Version
MATLAB 2018 a or later
EEGLAB 2019 or later
fMRIb [v1.2 or later

APPEAR Configuration Structure

APPEAR structure has the following fields that are needed for running the pipeline:

Having introduced the main structure information, the next part put all pieces together to run APPEAR on our demo example.

Demo Example

Please clone this repo as following:

gh repo clone obada-alzoubi/appear

%% Add required paths and functions
addpath('funcs');
addpath('eeglab2019_0');
[ALLEEG, ~, ~, ~] = eeglab;
close all;

%% Input data
sub_folder =strcat(pwd, '/demo/');
% data are in brain vision analyzer format
subj_eeg_file = 'subj1_EEG';
% If you want to use pulse ox. to detect QRS peaks
subj_ecg_file = 'subj1_ECG.1D';
%% Output folder
subj_out_folder = 'demo_out';
mkdir(subj_out_folder)

%% Store Configuration in EEG.APEAR
TR = 2;% seconds
slice_per_TR = 39; % slices per volume
scntme = 480; % Scan length in secs

Analyzer format. If you have other formats like ‘EDF’, you may want to edit the function to read the target format into the EEG object of EEGLAB. The function should use the same data structure as in EEGLAB.

%% Read EEG, channel names and Slice Markers (R128)
% Step 1
[EEG] = load_EEG(sub_folder,subj_eeg_file, scntme, TR, slice_per_TR);
% Set channel locations
EEG.chanlocs = loadbvef('BC-MR-32.bvef');

EEG.APEAR.Fs = 250;% Hz: frequency of the EEG output
EEG.APEAR.filterRange = [1 70];%Hz: filter EEG between 1 and 70 Hz
EEG.APEAR.BCG_Crorrection = 'Pulse_Ox'; % Recommended
EEG.APEAR.PulseOx_Fs = 40; % Hz
EEG.APEAR.ECG_ch_ind = 32; % ECG index (channel # 32)
EEG.APEAR.PulseOX.minHearteRate = 25; % minimum heart rate you expect

Please note that other parameters were also set inside load_EEG function. We are going to use Pulse Oximeter in this example. Thus, we need to read the pulse oximeter of the subject, which is store in subj1_ECG.1D. Then, we will apply peak detection and then match the sampling rate with EEG data. After that, we will store all information in a substructure under the APPEAR structure.

%% If we want to use Pulse Ox for BCG correction, add required fields
% Step 2
if ~isempty(subj_ecg_file) && strcmp(EEG.APEAR.BCG_Crorrection, 'Pulse_Ox')
    % Read and resample Pulse Ox., then detect R peaks
    [Peak_locations, pusleox_waveform] =
    pulseOx_DetectPeaks(strcat(sub_folder, subj_ecg_file),...
    EEG.APEAR.PulseOx_Fs , EEG.APEAR.Fs, EEG.APEAR.PulseOX.minHearteRate)
    ;
    % Save QRS peaks, Fs and waveform
    EEG.APEAR.PulseOX.Peaks = Peak_locations;
    EEG.APEAR.PulseOX.Fs = EEG.APEAR.Fs;
    EEG.APEAR.PulseOX.waveform = pusleox_waveform ;
end

In the previous code, pulseOx_DetectPeaks function does all the necessary jobs. If you have a different frequency configuration or specific pulse oximeter format, you need to change this function.

%% Run APEAR
[EEG2] = APPEAR(EEG, subj_out_folder, 'test');

%% Save final EEG
corrEEG_filename = strcat(subj_out_folder, '/', suffix, '_', 'eeg_p-2');
% As edf
pop_writebva(EEG2,corrEEG_filename);
% as MAT
save(strcat(corrEEG_filename, '.mat'),'EEG2');
% As CSV
csvwrite(strcat(corrEEG_filename, '.csv'),EEG2.data );

APPEAR Function Technical Details

APPEAR is a complete toolbox for processing and cleaning EEG data recorded inside the scanner. The code includes several steps to conduct the preprocessing. In this part, we highlight the main steps that are taken in the code.

[cbicind,~,~,~,~,tpblink,tpsac,~,singchan,muscleloc] =
icid(W*double(EEG.data),double(A),double(EEG.data),EEG.srate,EEG.times(end));

Sample of Cleaned data (Task and Resting-State Data )

Fig1