amisepa / brainbeats

The BrainBeats toolbox, implemented as an EEGLAB plugin, allows joint processing and analysis of EEG and cardiovascular signals (ECG/PPG).

BrainBeats

The BrainBeats toolbox, implemented as an EEGLAB plugin, allows joint processing and analysis of EEG and cardiovascular signals (ECG and PPG) for brain-heart interplay research. Both the general user interface (GUI) and command line are supported (see tutorial). BrainBeats currently supports: 1) Heartbeat-evoked potentials (HEP) and oscillations (HEO); 2) Extraction of EEG and HRV features; 3) Extraction of heart artifacts from EEG signals; 4) brain-heart coherence.

THREE METHODS AVAILABLE

1. Process EEG data for heartbeat-evoked potentials (HEP) analysis using ECG or PPG signals. Steps include signal processing of EEG and cardiovascular signals, inserting R-peak markers into the EEG data, segmentation around the R-peaks with optimal window length, time-frequency decomposition.

Example of HEP at the subject level, obtained from simultaneous EEG-ECG signals

Example of HEP at the subject level, obtained from simultaneous EEG-PPG signals

2. Extract EEG and HRV features from continuous data in the time, frequency, and nonlinear domains.

   • HRV time domain: SDNN, RMSSD, pNN50.

   • HRV frequency domain: VLF-power, ULF-power, LF-power, HF-power, LF:HF ratio, Total power.

   • HRV nonlinear domain: Poincare, fuzzy entropy, fractal dimension, PRSA.

   • EEG frequency domain: average band power (delta, theta, alpha, beta, gamma), individual alpha frequency (IAF), alpha asymmetry.

   • EEG nonlinear domain: fuzzy entropy, fractal dimension

Example of power spectral density (PSD) estimated from HRV and EEG data

Example of EEG features extracted from sample dataset

3. Remove heart components from EEG signals using ICA and ICLabel.

Example of extraction of cardiovascular components from EEG signals

4. Compute brain-heart coherence (beta version, please test and give feedback)

Example of several brain-heart coherence measures computed with BrainBeats from simultaneous EEG and ECG signals

Scalp topography showing scalp regions coherent with ECG signal for each frequency band

Requirements

• MATLAB installed (https://www.mathworks.com/downloads)
• EEGLAB installed (https://github.com/sccn/eeglab)
• Some data containing EEG and cardiovascular signals (ECG or PPG) within the same file (i.e. recorded simultaneously). Or use the tutorial dataset provided in this repository located in the "sample_data" folder.

Step-by-step tutorial

See our publication for a step-by-step tutorial using the sample dataset: https://www.jove.com/t/65829/brainbeats-as-an-open-source-eeglab-plugin-to-jointly-analyze-eeg

Full-text preprint: https://www.biorxiv.org/content/10.1101/2023.06.01.543272v3.full

Version history

v1.5 (5/2/2024) - METHOD 4 (brain-heart coherence) added

v1.4 (4/1/2024) - publication JoVE (methods 1, 2, 3)

brainbeats's Issues

hf array depends on the length of the data

size 4 x 1 for 120 seconds and size 11 x 1 for 300 seconds

Other missing function

At this point most users have given up. Testing is part of developing, make a second clone to check that it works.

Fix data scroll for MAC or use another one

It is important to be able to see the peaks and how they are detected

Infinity reference error

When running the first HEP method on the tutorial dataset using defaults I receive this error:

I have the REST1.2 toolbox installed, which did not fix the issue. I could only proceed when switching to average reference.

I use MATLAB r2023a and EEGLAB2023.1

Tutorial Error Method 2 PPG

When running the second method with PPG settings in the tutorial I get this error:

Also on MATLAB r2023 and EEGLAB2023.1

Cannot run alpha asymetry without Heart channel

I tried again for 20 minutes not using my modified functions. Did not work.

Running the tutorial

On the main branch, with the latest changes as of today.
started "brainbeats_tutorial"

This question poped up.

The first time, I answered no and got this error

The second time, I answered yes, and got this error

switch back to main branch as default

finish group stat analysis for features mode

try alternative method for detecting R peaks with noisy wearable ECG

see: https://ieeexplore.ieee.org/document/10416368

Add NaNs in features outputs when bad channels were not interpolated

add options for HRV frequency method in GUI

rename tutorial.m -> brainbeats_tutorial.m

"EEGLAB error in function get_eeg_features() at line 203:"

Hello and thank you for this - very useful - plugin

I' ve been trying to analyze a number of datasets and have been encountering the same error in each one that I have tested.

I'm using Matlab R2023a, latest version of EEGLAB and latest version of BrainBeats from github.

My datasets have 32 EEG channels + 1 ECG, and a duration of ~500sec, are referenced to average and have channel locations.

I'm using the mode "Extract EEG and HRV features" and the error occurs specifically when extracting EEG frequency domain features.

The following happens for all EEG channels, although not for the same frequency bands.

After not being able to detect individualized frequency bounds:

and then this error window appears:

I will appreciate any help as I have no clue about what could be causing this error or how to solve it
Thank you for your time!

add alpha asymmetry plot

Compute these measures if you can

https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5624990/#:~:text=used%20in%20biofeedback.-,RMSSD,of%20the%20total%20is%20obtained.

Remove the other ones (skewness, kurtosis) unless you have seen them elsewhere. You want measures that have a meaning and are positively correlated with parasympathetic activity (otherwise, say you have a difference in skewness, you have no idea what it means).

Do not remove ECG and add events to EEG structure

It is drastic to remove the ECG channel. Instead keep it by default. Also add the ECG peaks as EEGLAB events.

RR interpolation using SQI time series as well

add padding to MFE filtering

try to detect ECG channels automatically

hrv_features not saved in history when you select it in the GUI

add option to import ECG/PPG channels separately from EEG (e.g. BIDS data), with time synchrony check and fix if needed

Another one

Canceling erases the EEG structure

Function not found

add coh/pcoh/dc between EEG/ECG

How to use brainbeats output for LIMO?

Hello, I am trying to compare HEP on 2 conditions.
For this, I selected some part of my dataset and merged it into 1 file, and process with brainbeats_process

EEG_merged = [];
for i = 1:2:nEvents-1
start_latency = EEG.event(i).latency;
end_latency = EEG.event(i+1).latency;

EEG_temp = pop_select(EEG, 'point', [start_latency end_latency]);
if isempty(EEG_merged)
    EEG_merged = EEG_temp;
else
    EEG_merged = pop_mergeset(EEG_merged, EEG_temp, 0);
end

end
EEG_merged = brainbeats_process(EEG_merged,'analysis','hep','heart_signal','ECG','heart_channels',{'EKG'},'clean_rr','pchip','clean_eeg',true, 'parpool',false,'gpu',true,'vis',true,'save',true);
pop_saveset(EEG_merged, 'filename', [savefilename '_condition1_epoch.set'], 'filepath', savefolder);

after this job, I tried to use LIMO but It can't precompute, with error message 'eeg_getdatact error'

am I doing something wrong with brainbeats or there is something wrong with plugin? Sorry for low-level question..

Unable to process single subject

I am able to open the toolbox, but after I select all of the desired parameters and click Ok, I get the error message "EEGLab error in function run_checks() at line 160: Unable to resolve the name 'parallel.Settings'." I ran into this issue when using the sample data provided and when using my own data.

I use MATLAB version 2023b, EEGLab version 2024.0, and MacOS Sonoma 14.4.1. Please let me know if you need any more information.

Plugin menu overwrite EEG structure

Store the results in EEG.etc

Add HRV LOA criterion?

limits of agreement (LOA) criterion
https://www.frontiersin.org/journals/neuroscience/articles/10.3389/fnins.2020.594880/full

Long computation time on GPUs

I compared the computation time of the nonlinear EEG measures and found something interesting: On my gaming machine (Ryzen 5800x, 32gb RAM, and RTX 3080) the computation time with just parallel computing, but no GPU computation was actually much lower. It took about 1h for method 2 without GPU, but 2h 10min when utilizing GPU computation. I repeated this measure twice with similar results. Perhaps the GPU array allocation can be made more efficient...

cannot run tutorial with message "Unrecognized function or variable 'flaggedRatio'."

I am running tutorial with bioRxiv pdf file.
https://www.biorxiv.org/content/10.1101/2023.06.01.543272v1.full.pdf

to do this, I installed v1.0 from this github but error message popped.

Do you have any solution about this issue?

Tutorial error Method 1

When running the tutorial I get this error:

Also on MATLAB r2023a and EEGLAB2023.1.

Another one...

Add other qEEG features?

e.g. alpha/beta ratios (supposed to reflect emotional arousal: https://link.springer.com/article/10.1007/s10044-016-0567-6) and theta/beta ratio (supposed to reflect cognitive arousal: https://pubmed.ncbi.nlm.nih.gov/30604100/)

Browser of ECG still broken on Mac

Use the

https://www.mathworks.com/matlabcentral/answers/558370-how-to-generate-a-stacked-plot-with-a-scroll-bar

https://www.mathworks.com/help/images/add-scroll-panel-to-figure.html

"EEGLAB error in function gen_colormap() at line 402"

Hi,
I am doing the "Extract EEG & HRV features" single-subject analysis tutorial. Following the HRV analysis, I keep getting this error during the EEG analysis.