|
|
|
[[_TOC_]]
|
|
|
|
|
|
|
|
# Diagnostics
|
|
|
|
Throughout the pipeline the scripts make many decisions that result in marks on both channels and time segments. The criteria for these decisions are laid out in the configuration files, and the results and the intermediate stages are saved in the EEG structure. These matrices can be easily access and plotted to get a visual representation of what is happening behind the scenes.
|
|
|
|
|
|
|
|
To visualise some of the choices that were made in the pipeline either create your own plotting functions, or try running the diagnostics script. To learn more about how data structures and calculations see the end of this section.
|
|
|
|
|
|
|
|
**Using the Diagnostics Script**
|
|
|
|
Open up a EEG dataset that has complete the dipfit stage of the pipeline to get all of the available figures. Most typically these will have the ending *_dip.set.* Make sure that the diagnostics.m file is on the MATLAB path. Call the diagnostics function in the MATLAB editor:
|
|
|
|
```matlab
|
|
|
|
diagnostics(ALLEEG,'single');
|
|
|
|
```
|
|
|
|
|
|
|
|
or
|
|
|
|
|
|
|
|
```matlab
|
|
|
|
diagnostics(ALLEEG,'study');
|
|
|
|
```
|
|
|
|
By typing the function name you are calling the diagnostics script. This function needs two input values.
|
|
|
|
* 1. ALLEEG- (structure) - most often pass this function the ALLEEG structure so that it has access to all the datasets you have loaded. You can also use EEG if you are going to only access the current dataset.
|
|
|
|
|
|
|
|
* 2. type - (string) - The type of analysis you want to do
|
|
|
|
* 'single' - will preform calculations and plot figures pertaining to the **current** dataset.
|
|
|
|
* 'study' - will preform calculations and plot figures pertaining to **all** datasets loaded.
|
|
|
|
|
|
|
|
Figures will be generated and you can browse them as you would like. The figures contain some visual representations of the calculations that are being preformed based on the quality of the data file. Follow along below for a more in depth view of some of the figures.
|
|
|
|
|
|
|
|
# Data Quality
|
|
|
|
**Single**
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
The first plot is a general overview of how much good data has been found in your data set. If the % of time and the % of channels removed from your data is very high you might want to reconsider your experiment modality. From the figure below:
|
|
|
|
|
|
|
|
![diag4](/uploads/0264d39ab0337a36484d1867fd9bb4bf/diag4.png)
|
|
|
|
|
|
|
|
Looking into this example further you can see from the editor printout that there is:
|
|
|
|
* 41 bad channels out of 135
|
|
|
|
* ~21% of data time flagged as bad
|
|
|
|
|
|
|
|
The designation of *Bad* is based off a few simple calculations based on parameters in the configuration files. We will look at these calculations in more detail below, and go through which configs parameters change each of the criteria.
|
|
|
|
|
|
|
|
![diag7](/uploads/dc996102b39d4da75a173af582a53db6/diag7.png)
|
|
|
|
|
|
|
|
*As a side Note is is possible but not likely for a channel to be flagged for more than one of these classifications. This would mean diagnostics will find high numbers of bad channels but a lower number of removals. Make sure you look at the printout in the editor.*
|
|
|
|
|
|
|
|
|
|
|
|
**Study**
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
The study option will present something very similar to these pie graphs but it will be in a stack bar graph, and be done for all of the data sets loaded. Going up the y axis is the subject number, and the x axis is the percentage of channels or time.
|
|
|
|
|
|
|
|
![diagstudy1](/uploads/7921b4aa633da05254dde8e6de782628/diagstudy1.png)
|
|
|
|
|
|
|
|
|
|
|
|
# Channel Flags
|
|
|
|
Channel flags are the way that channels are identified and staged for removal. A few examples of channel flag calculations are:
|
|
|
|
* Standard Deviation (Comically Bad)
|
|
|
|
* High correlation (Bridging)
|
|
|
|
* Low Correlation
|
|
|
|
|
|
|
|
Diagnostics will present the data for the Standard Deviation and the Low correlation. At the moment the Bridging analysis is not saved to the EEG structure.
|
|
|
|
![diag1](/uploads/e847ad6b6edadcc445473fe0f31cfae1/diag1.png)
|
|
|
|
|
|
|
|
The figures below are separated into 3 sub figures to show how the calculations are done.
|
|
|
|
For example lets review the Standard deviation plot (Figure: 4) subplots from left to right.
|
|
|
|
* Sub Figure 1
|
|
|
|
This figure is the raw standard deviation values for each channels for every epoch of time. The colour represents the magnitude of the standard deviation there is for each of these epochs. In this particular case the dark red colour means there is a high deviation and the blue means lower, but the exact colouring will depend on your Matlab plot settings.
|
|
|
|
* Sub Figure 2
|
|
|
|
This plot expands on the values from the first sub figure. In this plot only the very highest values that pass the channel **z** criteria are selected and plotted as a 1. In this particular case blue means that the designated epoch was not over the specified z criteria. You can adjust the z criteria of the flagging by adjusting variables:
|
|
|
|
* ```[sd_chan_z] ``` for standard deviation. Default is 2.326 deviations, a higher number will produce less marks, lower will flag more.
|
|
|
|
* ```[r_chan_z]``` for correlations. Default is 2.326, a higher number will produce less marks, lower will flag more.
|
|
|
|
* Sub Figure 3
|
|
|
|
The third plot uses the results from the second plot. It adds up the marks for each of the channels and finds the % of each channel that was flagged. Looking at the example below the red segment had a high deviation, and produced a high % of the channel being covered in flags. This causes the waveform on the right to peak at this channel. This peak crosses the z threshold vertical line, meaning the channel has to much time in which it is comically bad. The criteria line can be adjusted left and right to allow for more or less acceptable deviation. You can adjust the criteria of the flagging by adjusting variables like:
|
|
|
|
* ```[sd_chan_p] ``` for standard deviation. Default is 0.1(10%) of the channel has to be flagged with the ```[sd_chan_z] ``` mark, a higher number will make the % required larger and thus less channels will be flagged.
|
|
|
|
* ```[r_chan_p]``` for correlations. Default is 0.1(10%)of the channel has to be flagged with the ```[r_chan_z] ``` mark, a higher number will make the % required larger and thus less channels will be flagged.
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
* Example 1:
|
|
|
|
* ```[sd_chan_z],2.236 ``` to ```[sd_chan_z],2 ```
|
|
|
|
* ```[sd_chan_p],0.1 ``` to ```[sd_chan_p],0.5 ```
|
|
|
|
This would **lower the criteria** for making the flags, and lower the amount that each channel needs to be flagged in order to marked as comically bad. This would flag more channels, and do **more removals** - potentially cleaning the data more, but reducing the amount of data.
|
|
|
|
|
|
|
|
* Example 2:
|
|
|
|
* ```[sd_chan_z],2.236 ``` to ```[sd_chan_z],3 ```
|
|
|
|
* ```[sd_chan_p],0.1 ``` to ```[sd_chan_p],0.2```
|
|
|
|
This would **increase the criteria** for making the flags, and increase the amount that each channel needs to be flagged in order to marked as comically bad. This would flag less channels, and do **less removals** - potentially reducing the data quality, but increasing the amount of data.
|
|
|
|
|
|
|
|
![diag8](/uploads/6f313553f164ba93e76fca7d8daa01c2/diag8.png)
|
|
|
|
|
|
|
|
**Red:** High deviation is visible, many flags are made, channels are over the % criteria and are marked for removal.
|
|
|
|
**Orange:** Some deviation is visible, some flags are made, channel is just over the % criteria and will be marked for removal. An adjustment to the criteria could swing this channel to be kept if needed.
|
|
|
|
**Yellow:** Little deviation is visible, no flags are made, channels are under the % criteria and not marked.
|
|
|
|
**Green:** The % criteria threshold. Any channel that peaks past this line will be marked for removal. As indicated this line can be moved based on your goals.
|
|
|
|
|
|
|
|
For more information on these calculations see the [Pipeline Scripts Page](https://git.sharcnet.ca/bucanl_pipelines/eeg_pipe_asr_amica/wikis/pipeline-scripts#scalpart).
|
|
|
|
|
|
|
|
# Time Flags
|
|
|
|
Time flags work in a very similar way as the channels, but marks are placed on time segments rather than channels. Since time dimension is important to look at now, the figures have been rotated starting with 1 at the top and 3 at the bottom. A few examples of time flag calculations are:
|
|
|
|
* Low Correlation
|
|
|
|
* Independent Component Standard Deviation (ICSD) (usually several rounds)
|
|
|
|
* Alpha and Beta Power (Not in Manual Removals)
|
|
|
|
|
|
|
|
![diag2](/uploads/5a10727f25463212a05bba1040c92f3e/diag2.png)
|
|
|
|
|
|
|
|
* Sub Figure 1
|
|
|
|
This figure works the same as before with channel marks, containing the raw calculated values of the test preformed.
|
|
|
|
* Sub Figure 2
|
|
|
|
This plot expands on the values from the first sub figure, and works the same as with channels. Any raw calculated value that is over the z criteria will be flagged a 1, anything below will be a 0. To adjust this criteria change the following in the config files:
|
|
|
|
* ```[epoch_z] ``` in ```c01_scalpart.cfg``` for correlations . Default is 2.326, a higher number will produce less flags, lower will flag more.
|
|
|
|
* ```[epoch_z]``` in ```c03_compart.cfg``` (or c6,c13,c14) for ICSD. Default is 2.326 deviations, a higher number will produce less flags, lower will flag more.
|
|
|
|
* Sub Figure 3
|
|
|
|
The third plot uses the results from the second plot. It adds up the marks for each column of time and finds the % of each
|
|
|
|
time segment that was flagged between all of the channels combined. The percentage is displayed as a waveform travelling through time. When the wave spikes high it means there is a time segment where many channels are all detecting bad data, and if it passes the horizontal line it is passed your designated criteria. That time segment will then be flagged and marked for removal. This segment of time will be gone for all of the channels. The criteria line can be adjusted up and down to allow for more or less acceptable deviation. You can adjust the criteria of the flagging by adjusting variables like:
|
|
|
|
* ```[epoch_p] ``` in ```c01_scalpart.cfg``` for correlations. Default is 0.1(10%) of the channels in this time frame need to be flagged with the ```[epoch_z] ``` mark, a higher number will make the % required larger and thus less time segments will be flagged.
|
|
|
|
* ```[epoch_p]``` in ```c03_compart.cfg``` (or c6,c13,c14) for ICSD. Default is 0.1(10%) of the channels in this time frame need to be flagged with the ```[epoch_z] ``` mark, a higher number will make the % required larger and thus less time segments will be flagged.
|
|
|
|
|
|
|
|
For more information on these calculations see the [Pipeline Scripts Page](https://git.sharcnet.ca/bucanl_pipelines/eeg_pipe_asr_amica/wikis/pipeline-scripts#scalpart).
|
|
|
|
|
|
|
|
# Component Classification
|
|
|
|
|
|
|
|
**Single**
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
Component classification can only be done on files that have successfully run through the complete dipfit script. It this script we make use of a plugin tool box developed by Laura Frolich called IC_MARC (classification of Independent Components of EEG into Multiple ARtifact Classes). This plugin will look at the components generated by AMICA, and attempt to classify them by their characteristics. It then saves the probability of the component belonging to one of the following categories.
|
|
|
|
* Neural
|
|
|
|
* Eye Blink
|
|
|
|
* Lateral Eye Movement
|
|
|
|
* Heartbeat
|
|
|
|
* Muscle
|
|
|
|
* Mixed Signal
|
|
|
|
|
|
|
|
These percentages sum to 100% and the category with the highest % normally selected as the guessed type. This information is useful in getting a general overview of what type of components can be found in your data, even if you don not completely trust its choices. We have made a slight adjustment to the ICMARC classification to make the non-mixed signals more sensitive. ICMARC will choose the final classification based on the highest percentage for all but one scenario.
|
|
|
|
* If the max classification is 'mixed' and under 75%, and the second highest classification is over 25%, then the final classification is switched to the second highest classification.
|
|
|
|
|
|
|
|
This is done in order to avoid signals that do contain a high amount of biological signal, but are classified as mixed by a slim margin. For example sometimes blinks were not identified as blinks since they had ~50% mixed and ~40% blink. So although mixed was the largest signal, for our purposes it should be considered a blink.
|
|
|
|
|
|
|
|
![diag3](/uploads/dfa4b9cb0401bc516f5b8ebe9524f874/diag3.png)
|
|
|
|
|
|
|
|
The pie graph in diagnostics shows the fraction of components that were placed in each of the categories. To the right of this is the breakdown of the % probabilities of the component belonging to each group. For example you can see that the first component (at the bottom), contains characteristics most like blink (navy) at ~65%, but it also contains characteristics like muscle and mixed signal that are about ~34% of the signal. The last ~1% is neural, lateral eye and heart, which do not match the component well.
|
|
|
|
|
|
|
|
These figures can give you a quick idea on how well you are isolating components. Ideally you are looking for components that have have a high % in one category, indicating a clear isolation.
|
|
|
|
|
|
|
|
**Study**
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
The study option will present something very similar to the pie graph but is represented by a stacked bar graph.
|
|
|
|
|
|
|
|
![diagstudy2](/uploads/d8de66bbee27f4896debfe420903fd5c/diagstudy2.png)
|
|
|
|
|
|
|
|
# Creating your own plotting functions
|
|
|
|
In order to create your own diagnostics tool you should make sure you are familiar with:
|
|
|
|
* The above content
|
|
|
|
* [Marks](https://git.sharcnet.ca/bucanl_eeglab_extensions/vised_marks/wikis/home) structure and creating by script.
|
|
|
|
* [Configuration files](https://git.sharcnet.ca/bucanl_eeglab_extensions/batch_context/wikis/configuration-files)
|
|
|
|
|
|
|
|
This section will use these concepts along with [plotting in matlab](https://www.mathworks.com/help/matlab/creating_plots/types-of-matlab-plots.html) and the EEG. structure.
|
|
|
|
|
|
|
|
|
|
|
|
All of the calculation results used in the figures generated by diagnostics are found in the EEG. structure.
|
|
|
|
![diag9](/uploads/aed82773e1d04202a638ab729afe7ba9/diag9.png)
|
|
|
|
For Example:
|
|
|
|
```data_sd_ch <135x1517> ``` is the matrix containing the results of the standard deviation test to find comically bad channels.
|
|
|
|
```c_data_sd_ch <135x1517> ``` is the corresponding flag matrix flagging 1 where the standard deviation was above the ```sd_chan_z``` critical value.
|
|
|
|
```marks.chan_info(2).flags``` is the corresponding channels marks where the channel had more % flagged then the ```sd_chan_p``` critical value.
|
|
|
|
This pattern matches for most of the marks.
|
|
|
|
|
|
|
|
**Single Subject - Pie Chart Example**
|
|
|
|
Below is the code for the pie chart separating the channel types. This code exclusively uses the marks structure for its data. The function ```pie``` can take a multitude of formatting inputs including explode,axis, and labels. The data needs to be a row vector with a number for each category. The fraction of the chart is based off of the % of each of these compared to one another.
|
|
|
|
```matlab
|
|
|
|
% Pie Chart
|
|
|
|
c1 = length(EEG.marks.chan_info(1).flags); % Collect Number of Epochs
|
|
|
|
c2 = length(find(EEG.marks.chan_info(2).flags)); % Collect the Number of Epochs flagged for mark 2 (ch_sd)
|
|
|
|
c3 = length(find(EEG.marks.chan_info(3).flags)); % Collect the Number of Epochs flagged for mark 3 (low_r)
|
|
|
|
c4 = length(find(EEG.marks.chan_info(4).flags)); % Collect the Number of Epochs flagged for mark 4 (bridge)
|
|
|
|
cm = length(find(EEG.marks.chan_info(1).flags)); % Collect the Number of Epochs flagged for mark 1 (manual)
|
|
|
|
c1 = c1-cm; % Update c1 to be the Number of Epochs not flagged for mark 1 (manual)
|
|
|
|
cpie = [c1 c2 c3 c4]; % Create cpie containing all of the other c values
|
|
|
|
figure; % Generate a figure window - nothing plotted yet
|
|
|
|
explode = [1 0 0 0]; % Set up input - Make c1 segmented out of the pie
|
|
|
|
ax1 = subplot(1,2,1); %Set up input - Make the pie chart the first plot of a of a 1x2 subplot grid
|
|
|
|
labels = {'Remaining Channels','Comically Bad','Low Correlation','Bridged'}; %Set up input - Create cell array of labels corresponding to c values
|
|
|
|
pie(ax1,cpie,explode,labels); % Plot pie graph using parameters just created.
|
|
|
|
colormap(jet); % Set the color scheme to be jet
|
|
|
|
title('Data Channel Classification'); % Set the title of the chart
|
|
|
|
```
|
|
|
|
|
|
|
|
**Single Subject - Calculate Flag and Mark Criteria Plot Example**
|
|
|
|
Below is the code for the s way subplot of calculating channel marks. This code exclusively uses the EEG. calculation matrices for its data. The function ```surf``` can take a multitude of formatting inputs including line style, axis, view, and face alpha. The data needs to be a matrix where the x and y values are gathered from the dimensions of the matrix, and the z values gathered on the data contained at each index. ```plot``` in this example only uses the optional axis location input. Both x and y need to be row matrices containing the co-ordinates of the data points to plot. To plot 2 lines on the same graph add a second row to the row vector, or run the plot command again with the new x row vector after using ```hold on;```.
|
|
|
|
|
|
|
|
```matlab
|
|
|
|
% Collect Data
|
|
|
|
z = EEG.data_sd_ch; % Finding the calculated values of the standard deviations
|
|
|
|
z(z>100) = 100; % Cap on the max deviation value, nice to show a better color gradient on the image. Just for looks.
|
|
|
|
|
|
|
|
figure; % Generate a figure window - nothing plotted yet
|
|
|
|
|
|
|
|
% Surface Plot 1
|
|
|
|
ax1 = subplot(1,3,1); % Select the subplot location for the upcoming plot to be space 1 in the 1x3.
|
|
|
|
surf(ax1,z,'LineStyle','none','FaceAlpha',0.9); % Plot the surface wave without grid lines and a 90% opacity.
|
|
|
|
view(0,90); % Rotate the surface plot so that it is 2D birds eye view
|
|
|
|
title('Standard Deviations'); %Add a title
|
|
|
|
xlabel('Epoch Number'); %Add a y- axis label
|
|
|
|
ylabel('Channel Number'); %Add a x- axis label
|
|
|
|
axis([0 size(z,2) 0 size(z,1)]); %Trim the image axis so that it is plotted as a tight fit. (xmin xmax ymin ymax)
|
|
|
|
colormap(jet); %Set the color scheme to be jet
|
|
|
|
|
|
|
|
% Surface Plot 2 - Compact version similar to Surface plot 1
|
|
|
|
ax2 = subplot(1,3,2); % Subplot location is 2 in the 1x3
|
|
|
|
surf(ax2,EEG.c_data_sd_ch,'LineStyle','none','FaceAlpha',0.9);view(0,90); % Data plotted this time is the flags EEG.c_data_sd_ch
|
|
|
|
title('Flags'); colormap(jet); axis([0 size(z1,2) 0 size(z1,1)]);
|
|
|
|
xlabel('Epoch Number'); ylabel('Channel Number');
|
|
|
|
|
|
|
|
% Critical Value Data
|
|
|
|
x = mean(EEG.c_data_sd_ch,2); % Row vector, Average of flags along each channel
|
|
|
|
y = 1:size(EEG.c_data_sd_ch,1); % Row vector, Channels numbers
|
|
|
|
x(:,2) = 0.1; % Second row vector in variable x, vertical line with equation x = 0.1
|
|
|
|
ax3 = subplot(1,3,3); % Subplot location
|
|
|
|
plot(ax3,x,y); % Plot of the x and y vectors to make a graph
|
|
|
|
title('Mean of Marks Critical Value'); % Standard plotting labels
|
|
|
|
xlabel('% Of Channel Flagged');
|
|
|
|
ylabel('Channel Number');
|
|
|
|
axis([-0.05 1 0 (length(x + 1))]); % Axis trimming (xmin xmax ymin ymax)
|
|
|
|
````
|
|
|
|
|
|
|
|
The time plot is very similar to this but has a few unique lines of code, adjusting the subplot locations and the x and y variables.
|
|
|
|
To see the code for other sections type:
|
|
|
|
```matlab
|
|
|
|
edit diagnostics
|
|
|
|
```
|
|
|
|
This will open up the function and you can see behind the scenes.
|
|
|
|
|
|
|
|
|
|
|
|
The rest of this wiki is in production.
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
# Fin Script QA
|
|
|
|
* Data Visualisation
|
|
|
|
* Component Selection
|
|
|
|
|
|
|
|
# Additional Scripts
|
|
|
|
* Dipole Fitting and Interpolation
|
|
|
|
* Segmentation
|
|
|
|
* Exporting
|
|
|
|
|
|
|
|
# Rebuild
|
|
|
|
Due to the nature of the pipeline being lossless we have created a script that essentially rebuilds the raw data from the finished file. There are only three occurrences when the original EEG.data values are changed.
|
|
|
|
* Lowpass filter
|
|
|
|
* Highpass filter
|
|
|
|
* Optional ASR pass
|
|
|
|
These pieces can be saved when the pipeline is run so that stats can be preformed on the residuals that are removed.
|
|
|
|
These pieces can also be added back to the data if a pipeline user wants to see how the percent change of the data. Dues to rounding errors there data is not exactly the same as it was but is usually has greater than 99% accuracy.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
[ :house: **Return to Main Page**](https://git.sharcnet.ca/bucanl_pipelines/eeg_pipe_asr_amica/wikis/home) |
|
|
|
\ No newline at end of file |