[3/3] Fastgraph: Plot Fastgraphs

[chinmaychinara91]

This PR is the 3rd and final part required for Fastgraph. It implements Fastgraph plotting, where each Fastgraph is a stacked area plot showing the distribution of stimulation-evoked responses across anatomical brain regions.

As the name suggests, Fastgraph stands for Functional-Anatomical STacked area graph. Each plot represents how stimulation of one site affects activity across other regions of the brain.

Prerequisite: Follow steps in PR #912

The GUI

Inputs

• Select scouts: The atlas (and optional scouts) used to plot the Fastgraphs.
• Color Fastgraph by region or by label: Selecting Region uses the region colors for the plot, and Label uses the above selected atlas label colors.
• Select region(s) to include: Only shows plots with colors from these selected region.
• Select method to sort the data This is for sorting the channel data within each hemisphere using one of the methods (RMS or Max Abs).
• Choose range to sort over The range to the above data sorting. Based on the paper, there are 3 ranges, early (0-60 ms), middle (60-250 ms) and late (250 to 600 ms) latencies. These latencies are the time delay between the stimulation trigger pulse and the measured brain response. Ideally, the middle latency is where we get the most significant response.
• Plot range: The range of the plot window.
• Edge transparency of plot: The alpha value of the boundaries in the stacked area plots per graph.
• Exclusion zone radius: Exclude analysis of contacts within this distance from the stimulation site. As per the paper 20mm is considered close as the contacts close to the stim site will always give very high response so it needs to be ignored.

Steps to use

1. Follow steps as in PR [2/3] Fastgraph: Remove SPES artifacts using EMD #912

2. Drag the artifact removed blocks (| rm spes | emd) to Process1 tab > Run > Import > Import recordings > Import MEG/EEG: Events. Set event name as STIM and epoch time -100 to 900 ms. For this sample data, we will be importing all the STIM events with a 1s epoch. The reason we chose this is due to the range of latencies (early, middle, late) mentioned above. Also note that appending the per session (represented by #1, #2) stim site info to the STIM events of the stimulation block earlier now helps in creating separate groups, else all would have clustered under one.
   
   

3. Drag the STIM groups to Process1 tab and average them by trial to get as under.
   
   

4. Ideally do it for all the stimulation blocks, but above just shows a sample of the data where A11-A12 shows low response and B3-B4 and B'3-B'4 show high response. To see the results, just drag the averaged trials to Process1 tab > Run > FAST graph > Plot Fastgraphs and set the values as shown in the process GUI image above to get the plot as under.
   
   

• The plots (Fastgraphs) are sorted from top left to bottom right in the order of Left hemisphere contacts (arranged anterior to posterior) followed by right hemisphere contacts (arranged anterior to posterior). The image below shows the implantation (taken from the paper).
  
  
• Each of the subplot (Fastgraph) has the data sorted as per the method we chose (here, RMS).
• The responses in each subplot above the x-axis represent the left hemisphere responses and below it represents the right hemisphere responses.
• Each subplot also tells which region gave the highest response. For e.g. in the Avg: STIM B'3-B'4 #1 Fastgraph, the parahippocampal L gave the highest response, in Avg: STIM B3-B4 #1 it was parahippocampal R and in Avg: STIM A11-A12 #1 it was superiortemporal R
• The bottom right most image is the legend that gives the color and region information for the plots, the time and amplitude ranges and also the L and R indicating above the x-axis represent the left hemisphere responses and below it represents the right hemisphere responses.

Some more examples

• Color by Region | Select region(s) to include: Frontal and Temporal
  
  

• Color by Label | Select region(s) to include: Select all
  
  

• Color by Label | Select region(s) to include: Frontal and Temporal
  
  

• Select scouts: parahippocampal L, parahippocampal R, superiortemporal R | Color by Region | Select region(s) to include: Select all
  
  

• Select scouts: parahippocampal L, parahippocampal R, superiortemporal R | Color by Label | Select region(s) to include: Select all
  
  

Associated PRs

1. [1/3] Fastgraph: Customize SPES (Nihon Kohden) #911
2. [2/3] Fastgraph: Remove SPES artifacts using EMD #912

Checklist

• Tutorial page - https://neuroimage.usc.edu/brainstorm/Tutorials/FastGraph
• Tutorial script - Requires merging PRs [1/3] Fastgraph: Customize SPES (Nihon Kohden) #911 and [2/3] Fastgraph: Remove SPES artifacts using EMD #912. For now good first draft for testing the end-to-end results, but might need changes based on the tutorial page. The tutorial data is here.

@jcmosher @Nastaranlotfi @yashvakilna

[rcassani]

@chinmaychinara91, To be reviewed, this PR should updated to be compatible with the changes in PR #911 and PR #912

[rcassani]

Please address the comments and perform the required changes.

[rcassani]

There is code to do this in Brainstorm. There is no need to add this external code.

See it in: figure_timefreq('GetLayoutPositions'). This is called when TF maps for all channels.

[rcassani]

No needed

[chinmaychinara91]

Added it in order to help the separate the display info for left and right contacts per FastGraph in the command window. But feel free to edit as you see fit.

[rcassani]

@chinmaychinara91, the file tutorial_fastgraph.m needs to be updated:

1. The process process_remove_spes_artifacts() was removed due to redundancy, the action is now performed with process_cutstim()
   See commit: 804e2fb in master

2. The process process_remove_drift_emd() was renamed to process_detrend_emd()
   See commit: 4d0a37f in master