Stimic - Stimulation Event List Creation

This article describes the procedure used for listing all the stimulations events through a semi-automated pipeline.

The details of the detection algorithm can be found here

Artifact Detection in macro-electrodes

Description

Goal : Detect (semi)-automatically stimulation artifacts on the macro-signals. Detection output must give the onset time of the stim, the channel(s) of stimulations and the frequency of the stim. A visual confirmation will be necessary before using the results. Here we only concentrate on locating the stimulation on the stimulation channels, with monopolar montage.

This will help to create a spreadsheet for each patient containing all the stimulation events and parameters :

• Patient ID
• Stimulation File Name
• Channel / Electrode
• Onset Time (s)
• Duration (s)
• Frequency (Hz)
• Intensity (mA?)
• Effect on the patient (if any)

Stimulation Parameters

Both frequency and intensity of the stimulation can change and affect the artifacts waveforms. The duration of the stimulation can also change but as we are only interested in detection the onset time, we will not consider it.

• Frequency range between 1Hz and 50Hz
• Intensity range between 0.5 mA and 4-5 mA

Pipeline

For each patient, for each file :

• 1 - Run the python script stim_clean_EDF_files.py which open all the EDF files, remove the non-EEG channels and bad channels. The script also check that each file contains the same number of channels and are ordered in the same way across each file. If a channel is missing, an NaN channel id added. It creates new FIF files

• 2 - For each file created in step 1, run the python script stim_detection_main.py which automatically detects the period of stimulation. It create an output csv file containing the events detected by the algorithm. Make sure that the frequencies of stimulations apart from 1 and 50 Hz are in the list called mid_freqs_hz.

Columns of interest are :

   - 4 : Type of the stimulation
   - 5 : Time (in seconds)
   - 8 : Duration (in seconds)
   - 7 : Channel index

• 3 - Visual check of the events : run micMac in Matlab and open the FIF file (Signals / Load Raw Signal / FIF Files). Import the csv file created in 1. Go in Events/Import/External Events. Indicate the correct columns number (You can use the Auto-detect button. Check the "zero-index for channel" checkbox . Check that the stimulation events are correct and manually add the missing ones. Once done, make sure to sort the event by time and export the events. It create another csv file, with this time all the stimulation events.

• 4 - Use the python script stim_frommicmactoexcel.py, for each csv file. It will convert and reorganized the micMac event file into an Excel file.

• 5 - Convert the micro .NS5 file into .edf files using the conversion Matlab function fileconv_nsx2edf. Use a downsampling factor of 6 to get a sampling frequency of 5kHz.

• 6 - Run the Python script stim_macrotomicro_corr_file.py for each fif and csv file. First you will need to find the time offset between the macro-file and the micro-file : micMac can be used, load the 2 files and either find the time offset manually or use the Resynch signals tool.

• 7 - Concatenate all the excel sheet into one, to get all the stimulations data into 1 file.

Output spreadsheet

The output spreadsheet will looks like this.This will allow to run further analysis.

Epoch creation

Once the Excel file containing all the event is done, an MNE Epoch structure can be created using the stim_create_epoch.py script. It takes as input the path to the excel stimulation file and the path pointing to the cleaned data directory.

3 options are available:

• resynch : If True, resynchronize the onset of the stimulation
• inverse_neg_stim : If True, inverse the negative stimulation so that all stimulation appears positive and the mean is not biased
• select_all_channels : If True select all the channel for creating the epoch, otherwise select only the stimulation channel