Tutorial EEG Workflow (APEX)#

This tutorial provides a step-by-step guide on running the example_EEG_workflow.py located inside the examples_APEX folder.

Adding the correct directory of files#

To recognize the TMSi Python interface folder, which is necessary for running the examples, your Python interpreter needs to know the corresponding path. Therefore, the first lines of code add this information. If you wish to store the recordings in a different folder than the default one, you can change the directory given in line 43.

import sys
import time
from os.path import join, dirname, realpath
Example_dir = dirname(realpath(__file__)) # directory of this file
modules_dir = join(Example_dir, '..') # directory with all modules
measurements_dir = join(Example_dir, '../measurements') # directory with all measurements
configs_dir = join(Example_dir, '../TMSiSDK\\tmsi_resources') # directory with configurations
sys.path.append(modules_dir)

Importing the required classes and functions from TMSi SDK#

These are the libraries which are implemented by TMSi and are required for the example script to work. They are used for purposes such as handling errors, writing recording files on PC, and plotting incoming data.

from TMSiSDK.tmsi_sdk import TMSiSDK, DeviceType, DeviceInterfaceType, DeviceState
from TMSiSDK.tmsi_errors.error import TMSiError
from TMSiFileFormats.file_writer import FileWriter, FileFormat

from TMSiGui.gui import Gui
from TMSiPlotterHelpers.impedance_plotter_helper import ImpedancePlotterHelper
from TMSiPlotterHelpers.signal_plotter_helper import SignalPlotterHelper

Finding connected devices#

It’s possible to have more than one device connected. The Python interface can be used to discover each device. Therefore, it’s necessary to specify the type of connected device as well as the interface via which the device is connected to PC (line 58). For APEX it can be either usb or bluetooth. Next, a list of connected devices (device type has already been specified) can be stored inside variable discoveryList. The next line of code (line 61) is a check to ensure that at least one device has been discovered. When one or multiple devices are found, the first device is opened. The handle to this discovered device is stored in the variable dev. The dev.open() command opens a connection to APEX.

    # Execute a device discovery. This returns a list of device-objects for every discovered device.
    TMSiSDK().discover(DeviceType.apex, DeviceInterfaceType.usb)
    discoveryList = TMSiSDK().get_device_list(DeviceType.apex)

    if (len(discoveryList) > 0):
        # Get the handle to the first discovered device.
        dev = discoveryList[0]
        
        # Open a connection to APEX
        dev.open()

Loading desired device configuration#

As shown in the beginning, the pre-defined configuration files are located inside the configs folder of the TMSi Python interface (TMSiSDKtmsi_resources). It is also possible to create custom configurations and save these as .xml files. In this example, a 32-channel configuration with EEG labeling is loaded to the device (line 75). Please make sure to load the device configuration after opening a connection to the device.

        if dev.get_num_channels()<32:
            # Load the EEG channel set and configuration
            print("load EEG config 24")
            dev.import_configuration(join(configs_dir, 'APEX_config_EEG24.xml'))
        else:
            # Load the EEG channel set and configuration
            print("load EEG config 32")
            dev.import_configuration(join(configs_dir, 'APEX_config_EEG32.xml'))

Initializing impedance plotter#

In most EEG measurements, it is common to monitor impedances prior to signal acquisition. Therefore, once the device configuration is set, a real-time plotter is initialized. As shown, the required graphical user interface (GUI) and plotter helper were initially imported from TMSiGui and TMSiPlotterHelpers. The plotter helper defines which plotter is shown by the GUI (for more information about the plotters, please read the Plotters Tutorial). In this case, the ImpedancePlotterHelper is initialized in line 85. Three parameters can be specified for the impedance plotter. The first parameter is the device that is passed to the Helper. The second variable, the layout variable, defines if the electrode impedances should be visualized as a head (for EEG) or in a Grid form (for HD-EMG). Finally, the impedances can be stored in a file: the third parameter defines the location and name of the file.

        # Check if there is already a plotter application in existence
        app = QApplication.instance()
        
        # Initialise the plotter application if there is no other plotter application
        if not app:
            app = QApplication(sys.argv)
        
        # Initialise the helper
        plotter_helper = ImpedancePlotterHelper(device=dev,
                                                 is_head_layout=True, 
                                                 file_storage = join(measurements_dir,"example_impedance_plot"))
        # Define the GUI object and show it 
        gui = Gui(plotter_helper = plotter_helper)
         # Enter the event loop
        app.exec_()

Initializing file writer#

The TMSi Python interface allows to record data in either .XDF or .Poly5 format. Therefore, the user is asked to provide a desired file format (line 98). Line 101 - 107 ensures that the specified file format is initialized. Here, it is also possible to specify the directory in which the recordings are stored. The default is set to the measurement_dir (defined earlier) located inside the TMSi Python interface folder. Please note, if neither .XDF nor .Poly5 is given as input, the data will be saved as .XDF (lines 105 - 107). Moreover, it is required for the file_writer to get a handle to the device specified in the discoveryList, which is done in line 110. The default file name is example_EEG_workflow. If the user wishes to change the file name, lines 101-107 can be edited.

        # Ask for desired file format
        file_format=input("Which file format do you want to use? (Options: xdf or poly5)\n")
        
        # Initialise the desired file-writer class and state its file path
        if file_format.lower()=='poly5':
            file_writer = FileWriter(FileFormat.poly5, join(measurements_dir,"example_EEG_workflow.poly5"))
        elif file_format.lower()=='xdf':
            file_writer = FileWriter(FileFormat.xdf, join(measurements_dir,"example_EEG_workflow.xdf"), add_ch_locs=True)
        else:
            print('File format not supported. File is saved to XDF-format.')
            file_writer = FileWriter(FileFormat.xdf, join(measurements_dir,"example_EEG_workflow.xdf"), add_ch_locs = True)
        
        # Define the handle to the device
        file_writer.open(dev)

Initializing signal plotter#

This step is very similar to initializing the impedance plotter. As plotting the real-time signal (instead of impedances) is desired, the SignalPlotterHelper is needed. The SignalPlotterHelper only needs the device as input parameter. The GUI is initialized based on the correct Helper and the GUI’s event loop is started by line 117.

As soon as the GUI is closed by the user, it is crucial to stop the file_writer and then close the connection to the device.

For simplicity, the explanation of try…except statement was skipped in this tutorial.

        # Initialise the new plotter helper
        plotter_helper = SignalPlotterHelper(device=dev)
        # Define the GUI object and show it 
        gui = Gui(plotter_helper = plotter_helper)
         # Enter the event loop
        app.exec_()
        
        # Close the file writer after GUI termination
        file_writer.close()
        
        # Close the connection to the device
        dev.close()

Summary#

To wrap it up, assuming that the device driver is installed, recording data in Python using a TMSi amplifier is done by following the steps below. You can use the same flow to write your own script.

Tutorial EEG Workflow (APEX)

Contents