[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

• Atlas to plot: The atlas used to plot the Fastgraphs with.
• 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.
• Atlas scout labels to plot: From the selected atlas, add which label to show on the plot (for multiple separate by commas).
• 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 (_emd) to Process1 tab > Run > Import > Import recordings > Import MEG/EEG: Events. Set event name as ODD, EVEN and epoch time -100 to 900 ms. For this sample data, we will be importing all the ODD and EVEN 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 ODD and EVEN events of the stimulation block earlier now helps in creating separate groups, else all would have clustered under one.
   
   

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

4. Ideally do it for all the entire 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 > Stimulation > Plot Fastgraphs and set the values as shown in the process GUI image above to 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: EVEN B'3-B'4 #1 Fastgraph, the parahippocampal L gave the highest response.
• 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.

5. We can stop in step 4, but some centers (like Cleveland Clinic) also further average the above obtained ODD and EVEN averages per session per stimulation site. E.g. averaging Avg: EVEN A11-A12 4 #1 (15 files) and Avg: ODD A11-A12 4 #1 (15 files) to get Avg: A11-A12 4 #1. Just drag the two averaged events to Process1 tab > Run > Average > Average files > Everything and rename it to Avg: A11-A12 4 #1.
   
   

The Fastgraph for these final averaged files is as under:

Some more examples

Color by Region and only show Frontal and Temporal regions

Color by Label and show all regions

Color by Label and only show Frontal and Temporal regions

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