Show PLS Result
This User's Guide only describes how to display a PLS result file. If you would like to know how to interpret your result, please refer to relevant papers.
In the PLS start window, click PET button and the button will be highlighted. Then click Show PLS Result for PET data button below, you will be asked to select a result file. Once you have selected the result file, the PET Result window will open (Figure 22). All slices are displayed, and slice indices are equal to X value plus Y value. This kind of labeling is very helpful in zooming.
Figure 22
If the result file contains a bootstrap result, the result window will display a view of Bootstrap Ratio first, and you can switch to a view of Brain LV by clicking View menu. Otherwise, the result window will display a view of Brain LV, and there will be no View menu.
Image Rotation menu provided limited amount of rotations for display only. If you want to change image orientation, you have to do so in Creating PET sessiondata file step.
If the crosshair bothers you, you can turn it off or change its color under Crosshair menu. You can click Zoom on menu to get a closer look at the region of interest.
Here we use two different thresholds (Pos / Neg Thresh) just in case the distribution of data is extremely biased. Therefore, it is still suggested to use symmetric threshold, and it is not recommended to modify the threshold arbitrarily, unless you know what you are doing.
Most information in result data is rendered under Windows menu.
Singular values are usually checked first (Figure 23).
Figure 23
Click Singular Values Plot under Windows menu, and the Singular Value Plot window will open (blue bar). If the value is very low for certain LVs, you may want to discard those LVs. If permutation test is included, you can also check whether those LVs are trustable by plotting the permuted singular value. Click Permuted Singular Values under View menu of Singular Value Plot window, Permuted Singular Plot window will open (red bar). It is the probability of those permuted singular values that are greater than the observed singular values. If the chances that permuted singular values are greater than the observed singular values are very high for certain LVs, you may also want to discard those LVs.
To view voxel values in the created datamat, click Voxel Intensity Response under Windows menu, and the response window will open behind the result window. If you click anywhere on the brain in the result window, the voxel value in the location that is specified by XYZ will be plotted (Figure 24).
Figure 24
Different subjects can be distinguished by legend marks. Subject average for each condition is provided in the bar graph. If you have more than one datamat, select the datamat that you would like to watch from the Datamat selection box.
You can use average intensity of the neighborhood voxels for intensity of the clicked voxel by specifying Neighborhood Size field (An edit box in Voxel Intensity Plot window). By default, it is 0, which means no neighborhood voxel is included. Otherwise, neighborhood size represents the distance (number of voxels) from the clicked voxel. In this case, the average intensity will include those voxels:
- The clicked voxel.
- The stabled voxels that meet the bootstrap threshold criteria, if bootstrap result is available.
- The clustered voxels of the current view. (Cluster mask of BrainLV View is different from that of Bootstrap View).
Do not set neighborhood size unnecessarily large, because the maximum number of neighborhood voxels is equal to the cubic of (SIZE * 2 + 1). e.g. Neighborhood Size 1 could have a neighborhood of 27, and Neighborhood Size 3 could have a neighborhood of 343, etc.
To extract voxel values from created datamats to a text file, you should prepare a voxel location text file in advance. This file contains XYZmm positions. It must be voxel location with unit in millimeter, instead of absolute voxel location XYZ. One row stands for each voxel, XYZmm are separated by spaces, like:
32.0 24.0 -20.0
-36.0 -48.0 -4.0
Click Multiple Voxels Extraction under Windows menu, and select the above voxel location file. Input only a prefix of the extracted file name, and you will be prompted to select a voxel neighborhood size to use average intensity of the neighborhood voxels for intensity of the selected voxels in your location file. It works the same way as the neighborhood voxels we discussed above. Click OK button, it will generate two kinds of files:
- prefix_MODULEvoxeldata.txt: This file includes all subjects in all groups. The rows of this file are in the order of subjects in conditions in groups.
- prefix_MODULE_grp_[subj]_voxeldata.txt: Each of these files will correspond to each session/datamat pair.
Columns of the extracted files stand for voxels in the order listed in the voxel location file. For E.R.fMRI, each voxel will take multiple columns which stand for multiple lags (the size of temporal window).
For Mean-Centering PLS, Non-Rotated Task PLS, or Multiblock PLS, you have the option to click Design LV and Design Scores Plot under Windows menu, and the plot window will open (Figure 25).
Figure 25
This window has three views: Brain Scores vs. Design Scores, Design Scores and Design LVs. Click View menu in this window to switch between views. If the result has more than one LV, select the LV that you would like to watch in the left panel. Usually the first thing you may want to check is the outlier subject(s) in the Brain Scores vs. Design Scores view. If there are any outlier subjects, you may want to reconsider whether you want to keep them or remove them. If you decide to remove them, you will have to run analysis again without those subjects.
For Mean-Centering PLS and Non-Rotated Task PLS, you also have the option to click Task PLS Brain Scores with CI under Windows menu, and the plot window will open (Figure 26).
Figure 26
For Behavior PLS or Multiblock PLS, the following submenu will also be available under Windows menu: Brain Scores vs. Behavior Data Plot, Datamat Correlations Response, and Datamat Correlations Plot.
Clicking Brain Scores vs. Behavior Data Plot submenu will start with the Brain Scores Plot window (Figure 27).
Figure 27
It displays brain scores vs. behavior data for each condition and each LV. If you have more than one group, select the group that you would like to watch in the upper left panel. If the result has more than one LV, select the LV that you would like to watch in the lower left panel. The title of each plot shows which LV is currently selected, and the variable r stands for correlation coefficient between behavior data and datamat.
You can click Show Brain Scores Overview under Plot menu to view all plots of different conditions and behavior measures (Figure 28).
Figure 28
Clicking Show Correlation Plot under Plot menu will display the correlation bar. It reflects the correlations between behavior data and brain scores. If bootstrap test is included, the correlation bar will come with an error bar specified by the upper and lower error range for the correlation. You can also select different groups and LVs in the same way above. Click Show Correlation Overview under Plot menu to view a correlation bar that includes all groups and conditions with all behavior measures (Figure 29).
Figure 29
Click Show Behavior LV Overview under Plot menu to view Behavior LV bar for all groups and conditions (Figure 30).
Figure 30
The Datamat correlations are correlation between behavior data and datamats. Click Datamat Correlations Response under Windows menu, and the response window will open behind the result window. If you click anywhere of the brain in result window, correlation value at XYZ will be plotted in bar graph (Figure 31).
Figure 31
Like datamat correlations in the above response window, Datamat Correlations Plot window also reflects the correlations between behavior data and datamats. However, Datamat Correlations Plot gives you an overview of the correlation values in the entire brain for each condition and each behavior measure (Figure 32).
Figure 32
Instead of selecting a group name from selection box, you need to enter a group ID, which is ordered sequentially, in Group Index field. Parameters in _Datamat Correlation_s frame below that are merely for display purposes. Only those voxels with values that are above the Threshold (and BS Threshold if bootstrap test is included) will be displayed. Voxel's datamat correlation value is referred by to its color.
We define it as a cluster if there are at lease N voxels connected together (5 voxels by default), and we call the one with the highest value a peak voxel. If the distance between the peak voxels of any two clusters is too close (10 mm by default), they will be treated as one cluster. Report menu provides you with capabilities of creating and loading a cluster report. You can also click Set Cluster Report Options under Report menu to change the default setting. Don't change Origin location field unless you have a good reason.
The accuracy of cluster report also depends on the recursion limitation of the MATLAB on your computer. Because of this recursion limit, you may encounter active voxels in the same cluster are separated into two or more clusters, some active clusters are not listed, the result of cluster report are different from one computer (or MATLAB version) to the other. Please refer to the FAQ.txt for more details.
Click Create Cluster Report under Report menu will generate cluster report for the current view (either Brain LV or Bootstrap). The report will display Voxel Mean, XYZ (absolute location), XYZ in mm, Brain LV Value or Bootstrap Value, and Cluster Size in voxels for the peak voxels of all clusters that are listed sequentially. It will also display the Source result file name, Current LV index, Current Threshold, Minimum Cluster Size, and Minimum Cluster Distance at the bottom (Figure 33).
Figure 33
There are two Save submenus and two Export submenus under File menu of Cluster Report window.
- Save to .mat file saves cluster_info structure into a MATLAB file, which can be loaded from Load Cluster Report under Report menu.
- Save to .txt file writes the content on Cluster Report window to a plain text file.
- Export All Locations writes XYZmm locations of all cluster voxels to a plain text file.
- Export Peak Location writes XYZmm locations of only peak voxels to a plain text file.
Select Cluster Mask under Report menu to display only the clustered voxels. However, you must create or load cluster report first. Then you can either close the cluster report window or leave it on.
If you would like to view a brain template underlying the result plot, you can click Load Background Image under File menu and select the brain template image as background image. The background image must have the same dimension as the images that are used in datamats.
Save brain region to IMG file takes the coordinates of the common brain region from the result file, and saves it to a brain region image file.
Save Current Display to IMG files saves the result image that is currently displayed to image files, and it also saves the colormap of current figure to a MATLAB file that is ended with "_cmap.mat".
Save the BLV (or BSR) result to IMG files saves the result values (either Brain LV or Bootstrap Ratio) that are currently displayed to image files.
The way to display a Structural MRI result file is the same as the way to display a PET result file.
The way to display a Blocked fMRI result file is the same as the way to display a PET result file.
The way to display an E.R.fMRI result file is a little bit different from the way to display a PET or a Blocked fMRI result file. Here are the differences:
E.R.fMRI displays all lags of temporal window in the result window (Figure 34).
Figure 34
Lag stands for scan in temporal window, which starts from 0. Lag is displayed on Y-axis, and each row displays all the slices that are selected. This is very different from Blocked fMRI or PET display, which do not have lag information. In Blocked fMRI and PET result window, all slices are displayed row by row.
Slices are selected from the left panel. When you specify a First Slice index, a Step, and a Last Slice index. It will display the first slice, and slices for every step. If any slices go beyond the last slice, they will not be displayed. When you select a voxel from LagXYZ field instead of clicking on the brain, please make sure that the slice index you entered is currently displayed. Otherwise, it will prompt warning that Invalid number in X, Y, or Z.
Here we use two different thresholds (Pos / Neg Thresh) just in case the distribution of data is extremely biased. Therefore, it is still suggested to use symmetric threshold, and it is not recommended to modify the threshold arbitrarily, unless you know what you are doing.
Response Function Plot window in E.R.fMRI plots the intensity change of a clicked voxel for the entire temporal window. Its counterpart in Blocked fMRI and PET is Voxel Intensity Response window, which does not have temporal window time series information.
In Response Function Plot window (Figure 35), all subjects for each condition take one row, with an average plotted at the end. Intensity value is displayed on Y-axis, and Lag number is displayed on X-axis. If bootstrap test is included, special symbols (small circle and diamond) will also be marked at top and bottom of each plot to represent the stable time points for the 1st & 2nd LVs. Click Stable off menu to hide those stable symbols.
Figure 35
There is an Export Data under Data menu of the response window. The row order of st_data variable in the exported data is determined by st_evt_list variable. However, we suggest people to use Multiple Voxels Extraction under Windows menu. This way, you can get all voxels' data at once. In addition, you do not have to worry about the order of rows, which is always in the order of subjects in conditions in groups.
You can change the display appearance by selecting submenus under Option menu. For example, to Hide / Show Average Plot; to Combine / Separate plots within conditions; to Enable / Disable Data Normalization; etc.
For Mean-Centering PLS, Non-Rotated Task PLS, or Multiblock PLS, there is a submenu under Windows menu for E.R.fMRI result. It is called Temporal Brain Scores Plot, and displays the brain scores for the entire temporal window. The appearance and usage of Temporal Brain Scores Plot window is very similar to Response Function Plot window. However, it opens in front of the result window. You need to click Plot button to display, and click LV radio button to select which LV you would like to watch.
For Behavior PLS or Multiblock PLS, there is a submenu under Windows menu for E.R.fMRI result. It is called Temporal Brain Correlation Plot, and displays the correlations between behavior data and brain scores for the entire temporal window. Since brain scores in result file do not contain time series information, we have to generate it from a subset of Datamats and Brain LV on fly for each lag of temporal window. The appearance and usage of Temporal Brain Correlation Plot window is very similar to the Temporal Brain Scores Plot window, and both windows open in front of the result window.
Datamat Correlations Response window in E.R.fMRI plots the correlations between behavior data and datamats of a clicked voxel for the entire temporal window. Its counterpart in Blocked fMRI and PET does not have time series information. The appearance and usage of Datamat Correlations Response window is very similar to the Temporal Brain Correlation Plot window. However, it opens behind the result window. If you click anywhere on the brain in result window, correlation value for the entire temporal window at XYZ will be plotted.
The way to display ERP result file is much different from the way to display Blocked fMRI, E.R.fMRI, or PET result file.
In PLS start window, click ERP button and it will be highlighted. Then click Show PLS Result for ERP data button below, you will be asked to select a result file. Once you select the result file, ERP Electrode Salience waveform window will open (Figure 36). It plots the salience on each electrode, and uses menu to control the display. If you click any waveform, a pink information box that contains channel name and wave name will be popped up.
Figure 36
Under Tool menu, there is a Display Options submenu. If bootstrap test is included, there is also a Bootstrap Options submenu.
In Display Options window, you can select which waveform(s) to be displayed. If you click Select All Waves button, all waves will be displayed. However, the more waves you selected, the longer it will take to display. You can also change axis intervals and font size by selecting the proper values beside them. If electrodes are distributed too sparse (or too crowded), you can also adjust the Wave Size scroll bar to change the wave size for every electrode.
Bootstrap stability is displayed in small circles or diamond. A circle will be marked at the time point that the bootstrap value exceeds the threshold. Bootstrap from different LV will take different horizontal lines. In Bootstrap Options window, there are 2 panels. The left panel displays the LV to be edited. You can only select 1 LV at a time to edit it. The parameters below that panel (Threshold etc.) can be edited and are all for the LV that you selected in the left panel. Click Reset to default value will reset those parameters to their default values. The right panel displays the LV to be displayed in Electrode Salience window. You can select one or more LVs to be displayed at the same time.
Click Legend On under Legend menu to display color legend for the wave and bootstrap displayed in the waveform window. Click Legend Off will remove the color legend. Because the limitation of MATLAB, it will be very slow if this is your first click of Legend On. Especially when there are a lot of waveforms displayed. After you click Legend Off, the subsequent clicks of Legend On will be quick.
Click Zoom on to have a closer look at a few electrodes. Click Zoom off to cancel the zooming status. Actually, we have another way to do it using Plot Detail under the View menu.
There are 3 submenus under Edit menu. They are: Select Electrodes with Rubberband, Select All Electrodes, and De-Select All Electrodes. As is known by the submenu names, they are used to select or deselect electrodes. The other way to select an electrode is to click the electrode name directly and make it bold. After an electrode is selected, its detail can be plotted using Plot Detail under View menu.
The reason that we call this menu Edit is because we can visually screen out bad subjects and/or electrodes in ERP Amplitude window immediately after creating or modifying ERP sessiondata file. In ERP Amplitude window, you can select a bad subject by selecting the bad subject waveform, and select a bad electrode by clicking its names and making it bold. Then click Modify Datamat under Edit menu, the Modify Datamat window opens, and the selected subjects and electrodes are preliminary un-highlighted. Once you click Modify button in Modify Datamat window, the bad subjects and electrodes will be removed from the sessiondata file.
This is the main menu to get information from the result data. There are several submenus under View menu, they are: Subject Amplitude, Average Amplitude, Spatiotemporal Correlation (only for Behavior PLS and Multiblock PLS), Plot Detail, Plot Singular Values, Plot Design Scores (not for Behavior PLS), Plot Temporal Scores (not for Behavior PLS), Plot Scalp Scores (only for Behavior PLS and Multiblock PLS), Plot Temporal Correlation (only for Behavior PLS and Multiblock PLS).
Subject Amplitude
Click Subject Amplitude under View menu will open Group Subject Amplitude waveform window. It plots the ERP amplitude of all subjects in all conditions and all groups that are used by this result.
Like Electrode Salience window, you can open Display Options window under Tool menu to select which waveform(s) to plot. However, this Display Options window is different from that from Electrode Salience window. In this Display Options window, you can easily select all subjects in a certain condition or all conditions in a certain subject by selecting the proper pull down menu.
Average Amplitude
Click Average Amplitude under View menu will open Grand Average Amplitude waveform window. It plots the average ERP amplitude of all subjects in a particular condition and a particular group.
It also has its own Display Options window under Tool menu to select which one to plot. If bootstrap test is included, you can also open Bootstrap Options window, and the Bootstrap Options window is exactly like what you see in the Electrode Salience window.
Under Tool menu of Grand Average Amplitude window, there are 2 more submenus: Display Condition Average and Display Condition Difference.
Display Condition Average allows you to display the average of the existing average waves. You can select several conditions from the left panel, give a name for the newly averaged condition, and click ->> button to make the averaged condition. The default averaged condition name will be the one with plus signs inserted among selected conditions.
For Display Condition Difference, it allows you to display the waveform of one condition subtracted by the other. Once you open the Condition Difference window, click Add button first. Then, select two conditions from the pull down menu.
Spatiotemporal Correlation
If it is a result of Behavior or Multiblock PLS, you can click Spatiotemporal Correlation under View menu to display the correlation waveform between behavior data and datamats. The usage is very similar to the Subject Amplitude waveform window, and its counterpart in other modules is called Datamat Correlation Plot.
It also has its own Display Options window under Tool menu to select which one to plot. If bootstrap test is included, you can also open Bootstrap Options window, and the Bootstrap Options window is exactly like what you see in the Electrode Salience window.
Plot Detail
If you only want to plot some of those electrodes, you can open Plot Detail window once you have selected one or more electrodes. You know the electrodes are selected if their names become bold. Click on the names can toggle the electrode select or deselect. You can also select or deselect electrodes using the tools provided under Edit Menu.
In Plot Detail window (Figure 37), it only displays the waveforms of the selected electrodes, with detail grid and units. If you click on any waveform, a pink information box that contains wave name, channel name, X & Y locations will be popped up.
Figure 37
Subject Amplitude for Given Timepoints
It looks like Plot Detail window with two more menus: Response Plot and Multiple Extraction, and you can plot the response of datamat value and extract multiple time points from this window.
To plot the response, click Response Plot menu in this window, and the Response Plot window will pop up and then stay behind the current window. The Response Plot window looks exactly the same as the Voxel Intensity Response window in PET.
To extract multiple time points, you need to prepare a time points file in advance. The time points file contains a single column of data, and each row represents a time point in milliseconds. When you click the Multiple Extraction menu, you will be prompted for this file. The behavior is the same as its counterparts in all other modules.
Other Submenus
The rest of submenus under View menu are very similar to the ones under Windows menu in E.R.fMRI module. For example, Plot Singular Values is equivalent to Singular Values Plot; Plot Design Scores is equivalent to Design LV and Design Scores Plot; Task PLS Scalp Scores with CI is equivalent to Task PLS Brain Scores with CI; Plot Temporal Scores is equivalent to Temporal Brain Scores Plot; Plot Scalp Scores is equivalent to Brain Scores vs. Behavior Data Plot; Plot Temporal Correlation is equivalent to Temporal Brain Correlation Plot.