Appendix

Appendix A: Test Data Sets

The subjects' data below is only for the purpose of illustrating the usage of PLS applications:

Download Testdata.zip (77.6 MB)

After unzip the above data, go to the unzipped "Testdata" folder and launch MATLAB from there. Follow the instructions below for the experiments.

PET Experiment

In this experiment, session files were created (in old style: session / datamat file pair), and result file has been generated.

There are 12 subjects with 8 conditions in this experiment. Click Show PLS Result for PET data button, and open the "pet_PETresult.mat" file. The displayed plot is Bootstrap Ratio Plot. Click View Brain LV under View menu to switch to Brain LV Plot.

Click Design LV and Design Scores Plot under Windows menu to open PLS Scores Plot window. As you can see that all "sent" conditions (sent enc, sent r1, sent r2, and sent r3) are positive, and all "pict" conditions are negative for LV1. This means that the red activation areas in Brain LV Plot correspond to sent conditions, while the blue activation areas correspond to pict conditions.

fMRI Experiment

In this experiment, you only have one subject's data. You can follow the steps below to see how to create sessiondata file, and run PLS analysis to generate result file.

This subject performed 2 tasks with 1 baseline condition (Task1, Task2, and Baseline). There are totally 5 runs that are located in 5 sub-folders (from dataset_001 to dataset_005). Each run lasts 6 minutes with TR of 2 seconds. So this gives us 180 time points (in TR) starting from 0, and each time point is represented by a scan image.

The onsets time points (in TR) of Task1 appeared at: 0 24 48 72 96 120 144 168

The onsets time points (in TR) of Task2 appeared at: 12 36 60 84 108 132 156

The onsets time points (in TR) of Baseline appeared at: 6 30 54 78 102 126 150

In this experiment, all images have been properly spatially and temporally realigned, normalized, and smoothed. In addition, only 5 slices from the entire brain were used. The first step of the experiment is to create a sessiondata file:

1. Click E.R.fMRI button in PLS start window, and click Session Profile for fMRI data button, the fMRI session window will open.
2. Type test in Datamat Prefix field.
3. Leave Across All Runs for Merge Data field.
4. Click Edit Conditions button, and Edit Condition window will open.
5. Type Task1 for condition1 field under Condition Name column, and click Add button.
6. When condition2 field shows up, type Task2 for condition2 and click Add button.
7. For condition3, type in Baseline and click Add button.
8. Now, click DONE button to close the Edit Condition window, and you will find the value in Number of Conditions field becomes 3.
9. Type 5 in Number of Runs field, and click Edit Runs button beside it, a Run Information window will open.
10. Type 180 in Number of Scans field.
11. Leave 0 for Number of Scans to be skipped field.
12. Click Browse button to open Select Data Files window.
13. Click dataset_001 in the Directories panel and click Select All button.
14. Click DONE button to close the Select Data Files window.
15. Click Load Onsets from a text file under Edit menu, and select onsets.txt file.
16. Keep Replicate trial information across run check box selected. This means that the onset values will be the same across all runs.
17. Click >> button to proceed to the second run.
18. You will find that the number 180 is already in Number of Scans field. If the number of scans that selected for your second run is not 180, you need to re-enter the number.
19. Leave 0 for Number of Scans to be skipped field.
20. Click Browse button like you did in the first run, and open Select Data Files window.
21. Click dataset_002 in the Directories panel and click Select All button.
22. Click DONE button to close the Select Data Files window.
23. Click >> button to proceed to the next run, and repeat the above steps for all 5 runs.
24. Click DONE button to close the Run Information window.
25. Click Create ST Datamat button, and PLS will open a Generate ST Datamat window.
26. In Generate ST Datamat window, leave everything as default, and click Create button to generate datamat. Once the generating process indicated by a progress bar is finished, you are back to the session window.
27. Click Close button to close the session window, and you are now in the start window.

You can now run PLS analysis using the above sessiondata file and datamat file. Usually, you should have more than one subject for PLS analysis, and each subject has one sessiondata file. This is especially required for permutation or bootstrap test. Here we only have one subject for illustration purpose, so the following step will run Mean-Centering PLS without permutation or bootstrap test:

1. Click E.R.fMRI button in PLS start window, and click Run PLS Analysis on fMRI data button, the PLS Analysis window will open.
2. Click Add button to open Select Session Profile Window.
3. Highlight test_fMRIsession.mat file name, and click >> button in the middle. Then click DONE to close Select Session Profile Window.
4. Click Mean-Centering PLS button in PLS option frame.
5. Leave everything as default, and only click Run button.
6. Now PLS will prompt you to enter a result file name. You can either select a new result file name, or simply use the default one test_fMRIresult.mat as file name.
7. Once PLS analysis is done, it goes back to the start window.
8. In order to view the result data, you need to click E.R.fMRI button in PLS start window, and click Show PLS Result for fMRI data button. PLS will prompt you to select a result file name, and you can select test_fMRIresult.mat to display this result file.

Appendix B: Command-Line PLS

As is mentioned earlier, the Command-Line PLS pls_analysis is the computation part of PLS Applications. However, its result cannot be displayed with GUI interface, because it is only part of the GUI result.

In order to run pls_analysis, the following input variables must be assigned properly:

• datamat_lst: Datamat list cell array. Each cell stands for one datamat (2-D Matrix), which is also referred as a group. All datamats must be in the form of subjects in conditions.

• num_subj_lst: Number of subject list array, containing the number of subjects in each group.

• num_cond: Number of conditions in datamat_lst.

• option: A struct of optional inputs. It can be:

  • method: This option will decide which PLS method that the program will use:

1. Mean-Centering Task PLS
2. Non-Rotated Task PLS
3. Regular Behavior PLS
4. Regular Multiblock PLS
5. Regular Multiblock PLS
6. Non-Rotated Multiblock PLS

If it is not specified, program will use default value 1.

• num_perm: If specified and num_perm > 0, PLS will run permutation test with num_perm amount of samples; otherwise, num_perm will use default value 0, and program will not run permutation test.
• is_struct: If it is not specified, is_struct will use default value 0. If specified and is_struct = 1, PLS will not permute conditions within a group. You only need to specify it when you run Non-Behavior Structure PLS and the segmented data is used.
• num_split: If specified and num_split > 0, PLS will run additonal loops for splithalf reliability test; otherwise num_split will take default value 0, and program will not run splithalf.
• num_boot: If specified and num_boot > 0, PLS will run bootstrap test with num_boot amount of samples; otherwise, num_boot will use default value 0, and program will not run bootstrap test.
• clim: Confidence level between 0 and 100. If not specified, program will use default value 95.
• bscan: In Multiblock PLS, you can specify a subset of conditions that are used in multiblock PLS behav block. e.g., bscan=[1 3] for 4 conditions. If it is not specified, it means that all the conditions are selected. Using the above example, bscan is equivalent to [1 2 3 4] for 4 conditions. This option can be applied to method 4 and 6.
• stacked_designdata: If you are choosing Non-Rotated Task PLS, Non-Rotated Behavior PLS, or Non-Rotated Multiblock PLS, you have to specify this 2-D numerical matrix.
• stacked_behavdata: If you are choosing any Behavior PLS or Multiblock PLS, you have to specify this 2-D numerical matrix.
• meancentering_type: Type of meancentering. If it is not specified, program will use default value 0. This option can be applied to method 1, 2, 4, and 6.
• cormode: correaltion mode determines correlation type to analyze. If it is not specified, program will use default value 0. This option can be applied to method 3, 4, 5, and 6.
• boot_type: It can be strat or nonstrat, and default is strat (Please do not change this value).

Once the input variables are prepared, you can run PLS analysis with the following command: result = pls_analysis(datamat_lst, num_subj_lst, num_cond, [option])

The output result is a structure variable that contains all the necessary items that are generated based on different PLS options. It could have items like:

• u: Brainlv or Salience
• s: Singular value
• v: Designlv or Behavlv
• usc: Brainscores or Scalpscores
• vsc: Designscores or Behavscores
• datamatcorrs_lst: Correlation of behavior data with datamat, only available in behavior PLS
• lvcorrs: Correlation of behavior data with usc, only available in behavior PLS
• perm_result: struct containing permutation result
• perm_splithalf: struct containing permutation splithalf
• boot_result: struct containing bootstrap result

Since command-line PLS requires you to provide a datamat cell array, it doesn’t have to be image data or EEG/MEG data that is required by PLS Applications. The following appendix is a tool in plscmd folder that allows people to plot the result of command-line PLS using Region of Interest (ROI) data.

Appendix C: Plot Bootstrap Results for Region of Interest (ROI) analyses

When you assign data to datamat_lst variable, it can be ROI values. The plotroi tool in plscmd folder to plot bootstrap result of ROI analysis on a template image. The color of each region reflects the corresponding bootstrap ratio (salience/salience standard error). Thresholds as well as minimum and maximum bootstrap ratios are shown on the accompanying color bar.

Before plotting any results, you need to make a flood-filled template image. This image can be created each time you use this tool. However, if you saved this flood-filled image, you can save some steps and load it directly.

Three files are required to run this tool, and optional files (below) make it easier to use.

Required files:

1. A template image or a flood-filled image:
2. Template image: The template image should be a gray-scale image in any format that can be read by MATLAB software. Image type and number of bits (e.g, 8 or 16) are not important. The centre of the ROIs and background should be whiter than the lines used to indicate ROI boundaries. All boundaries must be closed.
3. Flood-filled image: An image that is created by this tool based on the template image and ROI seed location file (below).
4. An ROI seed location text file: This file should have the following format: 1 252 263 CBM_Left 2 448 262 CBM_Right 3 266 157 AngularGy_Left 4 444 165 AngularGy_Right

The 1st column is ROI number, and would typically be a vector 1:MaxNumberOfROIs. Use of this module will be most efficient if the order of this file is the same order that you typically use for analysis.

The 2nd and 3rd colums are the x and y coordinates of a seed point location inside each ROI (integer). If your favourite drawing software does not provide this information, you can obtain these coordinates by displaying the image in MATLAB and using the ginput or getpts command to generate the coordinates.

The 4th column is the name of region. If you omit the 4th column, the name of region will be automatically called Region 1, Region 2 etc.

3. A bootstrap ratio text file: If you obtain the bootstrap data using the command-line PLS, it is actually:

result.boot_result.compare_u

You can save this variable as a text file using this MATLAB command:

save -ascii my_compare.txt result.boot_result.compare_u

Optional files:

1. A text file containg a column vector of ROIs used for the analysis. e.g.: 1

3

10

20 2. An image to use as an optional underlay for the results display (e.g., a brain anatomical). This image should be a gray-scale image in any format that can be read by MATLAB software. It must have the same dimensions as the template image. Hint: if you are displaying multiple anatomical images as underlay, make the background black.

Procedures:

1. Start MATLAB, add a path to plotroi folder in plscmd for plotroi tool.
2. Type plotroi to open the Information to plot ROI window.
3. If a flooded image is available, load flooded image and ROI seed location file. Otherwise, click on the radio button for template image, and load it with the ROI seed location file. Then, click Create Flooded Image File button. Once the flooded image file has been created, it remains loaded, and the name appears in the Flooded Image File box.
4. Load bootstrap ratio (compare) file.
5. Click Select ROIs button to select the ROIs used for the analysis. The initial order will be the same as the order provided in the seed location file. Highlight all ROI names (e.g., drag down with the mouse) and move to the Selected ROIs panel using the ">>" button. If your data are not in this order, you can move ROI name using UP or DOWN button in the Selected ROIs panel. The order is critically important. For future analyses, save the selected ROIs to a text file, under the "File" menu. The next time, you can go directly to "File" menu of the "Select ROIs" window and load the saved text file, and the ROIs will be properly selected and in the proper order. If you modify your analysis (e.g., drop ROIs), saving a separate text file of the new ROI numbers will also save your time.
6. Select the LV you would like to see, and input the threshold for the selected LV.
7. If you would like to keep the information you entered, you can click Save information figure in the File menu to save the data. This can be reloaded for re-plotting by clicking Load information figure, and go _Plo_t.
8. Before clicking Plot button, you can optionally input a title for the plotted ROI.
9. Once you click the Plot button, the plotted ROI figure will be displayed. The numbers at the right side of the color bar stands for the value for the corresponding color. The name of ROI will pop up by clicking an ROI. Minimum and Maximum bootstrap ratio thresholds are updated automatically for each LV. If you want to display two or more LVs using the same upper and lower values (same colormap intensity range), you can change these to your preferred min/max range. Only expansion of the colormaps is allowed. We do not allow the min/max to go below the overall maximum or above the overall minimum. Example: You have 2LVs you want to display side-by-side. LV1 range is +6 to -1; LV2 range is +4 to -4. They could be displayed on the same scale of +6 to -4, but not +4 to -4. Re-entering the LV number will reset the minimum and maximum values to the actual values in the bootstrap ratio results.
10. Optionally, if you have a brain anatomical image prepared, you can go to File menu and click Load background image to underlay the ROI with the brain anatomical image.
11. There are several other options under File menu. The Copy to Clipboard option is very useful, but only available for MS Window's version of MATLAB.

Sample data: The sample data below is only for the purpose of illustration the usage of plotroi tool:

Download Plotroi_testdata.zip (50 MB)