EStiMo

Table of Contents

• Overview
• Features
• How It Works
• Installation
• Running EStiMo for the First Time
  • Establishing Connection with NeurOne or Brain Products
  • Start EStiMo
  • Configuration Window
  • Calibration Process
  • Running Main Recording
• Configuration and Electrode Montage Files
  • TMS Protocol Structure
  • Electrode Selection Structure
  • Spatial Locations File Structure
  • Montage File Structure

Open-source toolbox for EEG-based Stimulation Monitoring (EStiMo) of brain states during TMS burst delivery

https://doi.org/10.1016/j.brs.2024.12.001

Overview:

EStiMo is an open-source Python toolbox for real-time EEG monitoring during Transcranial Magnetic Stimulation (TMS) sessions. It performs real-time analysis of Electroencephalography (EEG) signals, computing features online and visually representing them via a user-friendly graphical interface. These computations occur during the intervals between TMS pulse trains, providing valuable insights into brain activity.

Features:

• Real-Time EEG Analysis: Visualizes cortical activity during TMS sessions.
• Flexible Customization: Allows the use of custom montages, channel configurations, and feature settings.
• Seamless Integration: Compatible with NeurOne and Brain Products systems for data acquisition.

---

How It Works:

EStiMo operates in three main steps:

• Data Acquisition: EEG signals are streamed from NeurOne or Brain Products RDA systems.
• Feature Computation: Real-time calculation of up to six EEG features.
• Visualization: Processed data is visualized in an interactive GUI for easy monitoring.

Installation

EStiMo is designed to be conveniently portable and as such, does not necessitate a typical installation procedure. To use the software, ensure a Python 3 environment (recommended: Python 3.9) and follow these steps:

Clone the repository:

git clone https://nugit.drcmr.dk/Tools/EStiMo.git
cd EStiMo

Install dependencies:

pip install -r requirements.txt

Troubleshooting: If you encounter issues with dependencies, ensure that your Python environment is correctly configured (consider using virtual environments).

---

---

Running EStiMo for the First Time

Establishing Connection with NeurOne OR Brain Products Systems (RDA):

NeuroOne: The EStiMo software connects to NeurOne utilizing a serial port. The application anticipates data as input from the device. The last channel is intended to function as a stimulus trigger channel, which returns a value of 0 in the absence of triggers and alternate values when triggers are present. For further specifics regarding the connection setup, kindly refer to Bittium NeurOne real-time DigiOut functionality of NeurOne user manual (https://www.bittium.com/medical/bittium-neurone/).

Brain Product: The software forms a connection with Brain Products systems via the Remote Data Access (RDA) protocol, which is an integral part of the Brain Products Recorder. Hence, the Recorder is a necessary requirement. The connection is made via the ethernet port. Detailed information about the RDA protocol and connection process can be found in the Brain Product user manual (https://pressrelease.brainproducts.com/real-time-eeg/).

Quick connection setup: on the server computer where Brain Recorder software is running, Enable the RDA option in Configuration > Preferences …, select the Remote Data Access tab and tick the Enable Remote Data Access. Next, to enable receiving the data through Ethernet cable (maybe known as LAN cable), on the client computer which EstiMo will run, please go to Control Panel > Network and Sharing Center and open the Network Connection Details of the newly established Ethernet Connection. You need to make sure that the IPv4 address of the client computer is same as server computer. Do not change the IPv4 address on the server computer, only change it on the client computer and make sure they are following the same IPv4 address.

default configurations for the TMS_protocol.txt and electrode_selection.txt files for first-time users

Start EStiMo:

python EStiMo_GUI.py

1. Configuration Window:

Upon execution, the initial settings window will appear. These settings can be manually altered, or a configuration file (a txt file with a specific structure) could be imported instead. The montage can be adjusted by importing a csv file containing a matrix of size (n_channels, n_channels).

EEG channels can be manually selected or deselected to include or exclude them from the feature extraction process (please check Configuration and Electrode Montage Files). Selected channels are highlighted in blue. On the right side of the interface, the channels are displayed. Their positions correspond to the actual positions on the cap, guided by the file indicated at the top of the screen. This layout can be changed if needed. It should be noted that when changing, two files must be selected: one depicting the original cap layout, and the other containing only the channels used for feature computation. If all channels are needed, the same file can be loaded twice.

At the top of the window, the "Features and connection" bar can be selected, offering a choice of features for the connection setup. Once the settings are appropriately adjusted, the "Run program" button can be clicked to start the software. Up to 6 features among X number of features can be selected. The Threshold is also adjustable on the right side of each feature. Details are available in the EstiMo publication. (https://doi.org/10.1016/j.brs.2024.12.001)

After selecting the preferred features and establishing the connection, the user can start streaming by clicking the 'Run Program' button.

2. Calibration Process

Perform a baseline recording of EEG data during rest. The system will compute average values for each feature. The feature measurements are averaged across channels and displayed as plots on the right side of the screen. Note: Recalibration may be required if the montage, channels, or environment changes. The software includes a calibration function. During this process, it looks at the data to set a baseline for all used features. During calibration, the software calculates the mean value of all channels every second. Once calibration is over, it sets the thresholds (by default) at 10% of the distance between min a max, over, and below the maximum and minimum value recorded during the calibration.

3. Running main recording

Following the calibration phase, the main recording and feature measurements can start by Start/Stop button. Each plot's background will turn red if any of the thresholds are crossed. Deatils can be found in the EstiMo paper. (https://doi.org/10.1016/j.brs.2024.12.001).

Configuration and Electrode Montage Files:

TMS_Protocol.txt structure

This file includes several settings that can be changed by adjusting the value that follows the colon. The settings you can change are:

• time_between_trains: Specifies the interval between consecutive trains in seconds.
• cut_time: Defines the duration (in seconds) of the signal segment to ignore between trains. The signal is cut symmetrically, removing half of this value from both ends. This value should be set in seconds.
• number_of_channels: Sets the total number of EEG channels used. This would be the EEG channels excluding EOG and EMG channels. For NeuroOne system exclude trigger indicator channels as well. For BrainProducts system: number of streamed channels from Brain Recorder - 2
• number_of_lines: Indicates the number of past segment measurements displayed during the readout phase.
• eog_channel: Specifies the index of the EOG (electrooculogram) channel. Negative indices can be used to count from the end. Note: The last channel (-1) is always reserved for the trigger indicator.
• emg_channel: Specifies the index of the EMG (electromyogram) channel, following the same indexing rules as eog_channel.
• included_channels: These are the indexes of channels that are used to calculate features, from 0 (which is the first channel) to N (N represents the number of EEG channels). EOG, EMG, and trigger indicator channels are not included. Indexes correspond to the order of channels streamed from the EEG system. This should be filled as a list of integers.
• names: These are the names of the channels that are streamed. This should be filled as a list of integers or strings.
• alpha_range: Defines the frequency range for the alpha band (in Hz) as a list of integers (e.g., [8, 15]).
• beta_range: Defines the frequency range for the beta band (in Hz) as a list of integers (e.g., [16, 30]).
• theta_range: Defines the frequency range for the theta band (in Hz) as a list of integers (e.g., [4, 8]).
• expected_triggers: Specifies the number of triggers expected within a single train.
• expected_time: This is the time of the single train, measured in milliseconds.

✅ Example:

time_between_trains: 8
cut_time: 1
number_of_channels: 18
number_of_lines: 4
eog_channel: -3
emg_channel: -2
included_channels: [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]
names: [1,3,7,8,9,11,14,17,19,23,26,29,32,43,50,52, "EOG", "EMG"]
alpha_range: [8,15]
beta_range: [16,30]
theta_range: [4,8]
threshold_parameter: 2
expected_triggers: 10
expected_time: 2000
plot_len: 4

✅ Example: From 10-10 EEG montage, only 12 channels are used. In that case, as a first file the whole 10-10 montage should be loaded, and as a second a file containing only chosen 12 electrodes.

Structure of the Electrode_selection.txt

You can set paths for the files that contain spatial information in this file. The following are the available settings:

• full_cap_file_path: This is the path to the file showing the spatial location for the full cap.
• cap_file_path: This is the path to the file showing the spatial location only for the streamed channels.

The requirement for both files is purely based on practical reasons to make potential edits to the protocol easier. It's designed for users who only want to use a selected number of channels from a larger EEG cap montage.

⚠️ Please note: If you're using the entire cap, set both settings to the same path. If you don't have access to any of these files, use one of them for both options. However, this might require manual adjustment in the program settings.

Spatial Locations file structure

The files with spatial locations are managed using the 'mne' library from Python. The function called mne.channels.read_custom_montage is utilized for this purpose. The coordinates are transformed into 2D space using the same library. The way this function reads the file depends on the file format:

eeglab: '.loc', '.locs', '.eloc'
hydrocel: '.sfp'
matlab: '.csd'
asa electrode: '.elc'
generic (Theta-phi in degrees): '.txt'
standard BESA spherical: '.elp'
brainvision: '.bvef'

⚠️ Please note: The software was tested only using generic format.

Montage file structure

The montage file is an N by N array that functions as an array multiplying the signal (array multiplication). This means the signal can be adjusted according to the user's needs, for example by setting a specific type of reference. The file should be in .csv format, and values should be separated by a comma. The indexes follow the Python standard, which is horizontally from left to right and vertically from top to bottom.