[1/3] Fastgraph: Customize SPES (Nihon Kohden)

[chinmaychinara91]

This PR is the first part required for Fastgraph. It involves customizing the raw data.

Customize SPES (Nihon Kohden)

Linked to process_customize_spes_nk and it does the following:

• Finds Nihon Kohden "Stim Start" and "Stim Stop" events
• If provided, renames those stimulation block events
• Detects individual analog stimulation trigger pulses within each stimulation block
• If provided, splits detected trigger pulses into ODD and EVEN events, useful for alternating monophasic stimulation study (useful for studying Fastgraph plots - 3rd PR).

The GUI

Inputs

• Update stimulation start/stop event label: Gives an option to the user to rename the Stim Start and Stim Stop labels in the imported NK events if they want to. In this case, we are shortening the labels to SB and SE respectively. Came as a requirement from UTH as the channel names can get very long, thereby making the overall stimulation event label very long.
• Stimulation trigger channel: The stimulation trigger channel in the recordings (here, DC10)
• Update stimulation trigger label: Gives an option to the user to rename the stimulation trigger event label (here DC10) in the raw NK events if they want to (here, change to STIM). Came from UTH, but maybe some other centers might have their own way of naming, so good to have this option.
• Buffer time around stimulation block (in s): Required so that it contains the full stimulation segment plus some context before and after it (here, 5s). Used as a buffer for the time window for detecting the stimulation trigger.
• Add ''ODD'' and ''EVEN'' events (alternating monophasic stimulation): If we check this, then it creates alternating monophasic stimulations from the original stimulation event. This is useful in downstream analysis as the odd and even pulses may produce different responses. We will be using this for Fastgraph plots (3rd PR).

Steps to use

1. Load in the updated example test protocol [ NOTE: This preprocessed protocol involves running CAT12 segmentation to get all the anatomical information, the implantation done using Brainstorm, and then loading in the raw data and adding the locations from the implantation to it. These steps will be part of the tutorial].

2. Drag the Baseline > Link to raw file to the Process1 tab and click on Run > Stimulation > Customize SPES (Nihon Kohden).

3. Fill in the values as seen in the GUI figure above. Click Run. The raw data gets updated as under:
   
   

• Stim Start event label gets replaced by SB (short for stim begin - UTH follows this)
• Stim Stop event label gets replaced by SE (short for stim end - UTH follows this)
• DC10 triggers were detected, and the event was renamed as STIM
• ODD and EVEN events was created from the STIM events above
• NOTE: STIM, ODD and EVEN event labels are appended with the stim site information (e.g. T'3-T'4 4 #1 in the figure above where T'3-T'4 4 means stimulation was delivered between contacts T'3 and T'4 at 4 milliamps and the #1 means the first session. You can see in the image there is also a 2nd session which is T'3-T'4 4 #2. Analyzing each of these sessions separately is required during the downstream analysis, which will be clearer in the 3rd PR.

4. We can then just import the data by dragging the updated Baseline > Link to raw file to the Process1 tab and click on Run > Import > Import recordings > Import MEG/EEG: Events. Set event name as SB and epoch time -5000 to 35000. For this sample data, we will be importing all SB events with an epoch of 40s (30s stimulation block with a buffer of 5s around it so that it contains the full stimulation segment plus some context before and after it).
   
   

Associated PRs

1. [2/3] Fastgraph: Remove SPES artifacts using EMD #912
2. Plot Fastgraphs (3rd PR) - TO BE ADDED

@jcmosher @Nastaranlotfi @yashvakilna

[Nastaranlotfi]

@rcassani , We need to import the stim blocks first, in order to determine which stim rates we have and stim lines. After the blocks are loaded, then we can detect the events. If we detect events first in the raw file, we get way too many extraneous events throughout the raw file. So restricting the event detection AFTER the stim block loading is strongly preferred.

[rcassani]

Hi @Nastaranlotfi, I do not really understand what is shown the shared screenshot. Can you provide more context on what is exactly what cannot be done in the raw data, but that is possible to be done with in the imported data?

[rcassani]

@chinmaychinara91, from yesterday's discussion doing the event labelling on the raw file is straight forward, right?

[chinmaychinara91]

@chinmaychinara91, from yesterday's discussion doing the event labelling on the raw file is straight forward, right?

@rcassani It is straight forward, but I observed something, let me explain in detail to make it clearer.

1. As per our discussion and your recommendation, in the raw file for the example test protocol provided above, the trigger line used is DC10 and we can correctly get these events Run > Events > Detect Analog triggers.

2. We then create two copies of the events DC10, one called ODD that will contain the odd instances of DC10 event (delete the even instances in the ODD group) and the other called EVEN that will contain the even instances of the DC10 event (delete the odd instances in the EVEN group). Two approaches here:

• If we do this ODD-EVEN creation in the raw itself and then import the data (Run > Import > Import recordings > Import MEG/EEG events with Stim Start as the event), the problem is that the ordering of imported ODD and EVEN per stimulation block is incorrect, as the ODD and EVEN are created considering the entire DC10 for the whole recording in the raw and then imported. As you can see in the time series image below, the ordering of EVEN and ODD triggers should be reversed.

• Now if we create the ODD and EVEN after importing the data, we are creating these events based on the local DC10 event per stimulation block. So this gives the correct ordering.

The screenshot shared by @Nastaranlotfi is for another proprietary data that UTH has, but I feel with the 2nd approach (i.e. creating ODD EVEN after importing the data) it should resolve all the issues.

Also, since we are creating this DC10 event in the raw itself, so we can remove the data import process
(process_import_data_event) and detection of triggers (process_evt_detect_analog) out of the current Load SPES script, as the users can separately do that first.

We can now call this routine something like Preprocess SPES rather than Load SPES as it will majorly involve renaming the Stim Starts and Stim Stops and creating ODD EVEN events.

Hope it makes things clearer. Once we all come to a common understanding, I will then proceed with making the changes.

[rcassani]

Now if we create the ODD and EVEN after importing the data, we are creating these events based on the local DC10 event per stimulation block. So this gives the correct ordering.

@chinmaychinara91 on processing the raw file, you have complete control on how create the ODD and EVEN events. If it is needed to restart the ODD-EVEN sequence for each stimulation block:

LOAD the `sEvents` structure
CREATE Groups of instances of DC10 using the stimulation block
CREATE Events ODD and EVEN without instances
FOR each Group
   CREATE events ODD and EVEN according to the instance of DC10 in the block
   APPEND events ODD and EVEN   

We then create two copies of the events DC10, one called ODD that will contain the odd instances of DC10 event (delete the even instances in the ODD group) and the other called EVEN that will contain the even instances of the DC10 event (delete the odd instances in the EVEN group). Two approaches here:

@chinmaychinara91, This was my suggestion as I did not know the ODD-EVEN was per stimulation block. You had all the information and skills to do it properly.

[chinmaychinara91]

@rcassani thank you for the clarification. I will go ahead and make the changes accordingly.

[chinmaychinara91]

Closing this PR and moving things to #913 for a clean history.

[rcassani]

Ok, we continue on #913

Just a small note, this PR would have merged with squash, thus the commit history gets collapsed anyway, so to have a "clean history" isn't really a concern. Keeping the same feature in one PR is valuable as it keeps the full conversation, decisions, and code evolution in one place. Moving to new PRs makes that harder to trace later.

[chinmaychinara91]

@rcassani Thank you for the clarification. That makes sense. I was thinking of keeping the final changes easier to review, but I understand your point, and that keeping the discussion/code evolution in one PR is better for traceability. I’ll keep this in mind for future PRs.

[rcassani]

This PR is reopened, following the in-person discussion
FYI @tmedani

[chinmaychinara91]

@rcassani, I have updated the description with details.