Partial least squares (PLS), which was first introduced to the neuroimaging community in 1996 (McIntosh et al., 1996), has proven to be a robust method for extracting distributed signal changes related to changing task demands (Mean-Centering PLS and Non-Rotated Task PLS). It has also been applied to measuring distributed patterns that impact on task performance (Regular Behav PLS, Non-Rotated Behav PLS and Multiblock PLS) and finally to task dependent changes in the relation between brain regions. This latter application is an assessment of functional connectivity or the correlation between neural elements (Seed PLS). PLS analysis has been used to characterize distributed signals measured by neuroimaging methods like positron emission tomography (PET), event-related functional magnetic resonance imaging (E.R.fMRI), Blocked fMRI, Structural MRI, event-related potentials (ERP) and magnetoencephalography (MEG).

PLSgui is a MATLAB program with a graphic user interface (GUI) driven by messages from mouse and keyboard. As an alternative, this user interface can also be driven by batch_plsgui command (see Batch Process), which is part of PLSgui program. PLScmd program (see Appendix B) is a command-line PLS, and it is a separate program that is not compatible with PLSgui. Both PLSgui and PLScmd can be downloaded from our Download Files web page.

For PET, Structural MRI, E.R.fMRI and Blocked fMRI, PLSgui is compatible with both ANALYZE format images (Mayo Clinic) and NIfTI format images (National Institutes of Health). For ERP (including MEG), it can read some of the binary data directly; such as NeuroScan average data, ANT's average data, EGI's simple-binary data, as well as tab (or space) delimited text files from any system.

This User's Guide intend to show how to use PLSgui program to those users who have already understood the PLS method. If PLS is new to you, please read relevant articles first.

2. Program Support

Here are the links to some useful web pages for the PLSgui program:

For on-line help: http://www.rotman-baycrest.on.ca/pls//UserGuide.htm
To download files: http://www.rotman-baycrest.on.ca/pls/source
For the latest update: http://www.rotman-baycrest.on.ca/pls/whatsnew.txt
Frequently asked questions: http://www.rotman-baycrest.on.ca/pls/FAQ.txt
To post questions: http://www.rotman-baycrest.on.ca/index.php?section=105
Event Calendar: http://www.rotman-baycrest.on.ca/index.php?section=107
Journal Articles: http://www.rotman-baycrest.on.ca/index.php?section=101

3. System Requirement

The PLSgui program runs from MATLAB Version 5.3.1 and above, platform independent. It has been tested up to MATLAB Version 7.4.0 (R2007a). Since PLSgui takes in all the useful information in the raw images, we suggest that you would better add as much memory as your system can support. If you have MATLAB Version 7 (R14) and above, All except ERP module in PLSgui will automatically take advantage of its single precision math operation feature, except you are using Intel 64-bit machine. According to MATLAB Bug Report ID 268001, MATLAB will give completely wrong result when performing single precision math operation on an Intel 64-bit machine. Therefore, when PLSgui detects that the MATLAB is running on a 64-bit computer, it will confirm that whether this system is a 64-bit machine. If you don’t know, the program will treat it as an Intel 64-bit machine, and will not perform single precision math operation.

If you do not have powerful system with lots of memory, you might want to consider re-sampling the raw images to a larger voxel size. When you increase the voxel size, the total amount of voxels reduces, and the dataset size also reduces.

4. Getting Started

In the MATLAB command window, type plsgui (make sure that the PLSgui program is in the MATLAB searching path), and you will see the start window (Figure 1).

Figure 1

As you can see in this start window, there are 5 buttons on top row, which stand for 5 PLS modules: PET, ERP, E.R.fMRI, Blocked fMRI, and Structural MRI. You must first select which module you would like to run. Below this top row, you will find 4 more buttons that indicates the basic flow of an experiment: Session Profile, Run PLS Analysis, Show PLS Result, and CLOSE, where clicking CLOSE button will close this start window. This User's Guide uses this basic flow as a thread for further introduction. Please follow the flow from top to bottom.

There are two submenus under Tools menu. One is Save GUI Positions. It is used to save size & location of all PLSgui windows. Uncheck it if you do not want size & location of GUI windows to be saved. The other one is Save Display Setting for PET/MRI. This is used to save the panel parameters (like threshold etc.) in the result windows for PET, E.R.fMRI, Blocked fMRI and Structural MRI.

Caution: Please remember that all the PLSgui generated files (like session file, datamat file, result file, etc.) must be kept in the same directory. The reason that we made the program to behave this way is that we would like to move those PLSgui generated files across the platforms without having to store individual folders in those files.

Please follow the steps below to learn how to use the PLSgui program.

5. Session / Datamat file pairs

We need session / datamat file pairs to run PLS analysis. For PET, ERP and Structural MRI module, session file is only used for creating datamat file, and only datamat file is used for displaying results. However, for E.R.fMRI and Blocked fMRI module, session file and datamat file must exist in pair, and both will be used for displaying results.

In order to create session / datamat file, raw data (scan image, ERP data etc.) must be saved in following ways before launch plsgui:

For PET scan image and ERP data, each subject should have its own directory containing PET images or ERP data of all conditions for this subject, and all subjects' directories should under the same (parent) directory.

For E.R.fMRI and Blocked fMRI data, each run should have its own directory containing scan images of all conditions for this run. All selected image file names in the run directory should be sorted in alphabetic ascend order that represent scans of this run in time series sequence.

For Structural MRI data, all subjects with all conditions are kept in a single directory.

PLSgui can take scan image that is either in ANALYZE format (Mayo Clinic) or in NIfTI format (National Institutes of Health) to create PET, E.R.fMRI, Blocked fMRI, and Structural MRI datamat. It can also take some of the binary data directly, such as NeuroScan average data, ANT's average data, EGI's simple-binary data, as well as delimited text files from any system to create ERP datamat.

All raw data must be properly pre-processed (registered to the same brain template, smoothed with some filters, etc.) prior to launch plsgui.

5.1. Creating PET session file

In the PLSgui start window, click PET button and the button will be highlighted. Then click Session Profile for PET data button below, the session window will open (Figure 2).

Figure 2

In the session window, Session Description is an optional field, which reminds you what this session is for.

Datamat Prefix is used to compose a file name for datamat file. For example, if you put demo in this field, the datamat file will become demo_PETdatamat.mat.

Click Input Conditions button, and add condition names one by one into the Edit Condition window. When you click DONE, Number of Conditions will show how many conditions you have selected.

As we mentioned above, all PET scans for each subject should be kept in one directory, and all subjects for one analysis should be under a single directory. If a PET file is in NIfTI image and contains multiple-scans, it must be expanded to multiple single-scan files with MATLAB program expand_nii_scan.m that is included in PLSgui.

Now, click Select Subjects button, and Edit Subject Directory window will open (Figure 3).

Figure 3

There is an edit box called Number of character for subject initial in the Edit Subject Directory window. Change the value from -1 to the length of subject initial if your subject files follow the following Consistent Naming Across Subjects rule:

All subject files consist two portions, subject initial portion and condition name portion. e.g. SubjInit1_CondName1;
Across all subject directories, the condition name portion should be the same for the same condition;
Within each subject directory, the subject initial portion should be the same for all conditions of this subject;

Click Add button, and Subject Directory Detail window will open (Figure 4).

Figure 4

If your subject files follow the Consistent Naming Across Subjects rule, follow the steps below:

Select one of subjects that will be used in this datamat group (Note: Remember that only select 1 subject at this time).
If you have Consistent Naming Across Subjects, you will notice that the File names are the same across subjects checkbox is checked. Uncheck it if you want to disable this feature.
Go to right hand side, select correct subject files that match the inputted conditions at their left side. Make sure that no subject file can be duplicated.
If you have multiple subjects in this datamat group, you can now select the rest of subjects by holding Shift or Ctrl key combination while selecting (Note: You can not do multiple selection before this step).
Click Done button when you finish, and it returns to Session Information window.

If your subject files do not follow the Consistent Naming Across Subjects rule, you can still follow the steps above. However, you will have to go to Edit Subject Directory window, click Edit button, and select correct subject files to match the inputted conditions for each single subject.

5.2. Creating PET datamat file

In PET session window, click Create Datamat button to open Create PET Datamat window.

There are two ways to define brain region:

Use pre-defined brain region image file. It should be the same size as any subject image. The intensity of brain region image should be either 0 or 1 (binary image), where 1 stands for the brain region.
Define brain region automatically with a threshold. If a voxel's intensity is greater than the threshold multiplied by the maximum intensity, it is considered as a brain voxel. Since any voxel intensity that is less than the threshold multiplied by the maximum intensity will be treated non-brain region, we require that the minimum of image intensity should be no less than 0.

If Normalize data with volume mean is checked, datamat value will be the stacked volume intensity divided by the average intensity for each volume; otherwise, datamat value will just be the stacked volume intensity. Please be aware that by default Normalize data with volume mean is checked for PET data.

Click Merge Conditions button to combine two or more conditions together to a new condition by averaging them.

Now, click Create button to generate PET datamat file.

5.3. Creating ERP session file

In the PLSgui start window, click ERP button and the button will be highlighted. Then click Session Profile for ERP data button below, the session window will open (Figure 5).

Figure 5

In the session window, Session Description is an optional field, which reminds you what this session is for.

Datamat Prefix is used to compose file names for ERP datamat file and ERP data file. For example, if you put demo in this field, demo_ERPdatamat.mat will be ERP datamat file name and demo_ERPdata.mat will be ERP data file name.

Digitization Interval is the inverse of sampling rate. It is in millisecond (default is 2ms).

Prestim Baseline shows how early the time points start before stimulus is applied to a subject. It is also in millisecond (default is 0), and the value should be less than or equal to 0.

Click Input Conditions button, and add condition names one by one into the Edit Condition window. When you click DONE, Number of Conditions will show how many conditions you have selected.

As we mentioned at the beginning of Session / Datamat file pairs section, all ERP data for each subject should be kept in one directory, and all subjects for one analysis should be under a single directory. Now, click Select Subjects button to select and edit subjects in subject directory. The steps are the same as those in PET.

If ERP data is a delimited text file, each row usually stands for an electrode channel and each column usually stands for a time point. However, column can be used for channel if Channel in column check box is selected.

In order to match row (or column) of ERP data with electrode channel name, you need to click Edit Channel Order button. If your ERP data are binary files, an additional Select an EEG format window will popup, and you can select the proper vendor name and machine format. No matter your ERP data are binary files or plain text files, you will end up with an Edit Channel Order window (Figure 6).

Figure 6

What on the left panel of Edit Channel Order window is a complete channel name list based on the two system boxes below that panel. You can either manually select and add them to the right panel (you only need to do this once), or load from an existing channel list text file that you have saved before through File menu (much more conveniently). Click DONE when finish, and Number of Channels will show how many channels you selected.

In the lower left corner of the Edit Channel Order window, you can select different scalp electrode location systems and sub-systems. When you change the system or sub-system, you can notice that channel name list on the left panel of Edit Channel Order window changes.

What if you have a scalp electrode system can not be found in the system boxes (e.g. Standard 10-20 EEG System with 19 cap electrodes)? Please follow the steps below to add your own system:

Put all electrode names on a piece of grid paper, and make sure that they are spatially located appropriately.
Select an origin for XY coordinates. You can pick any point (on or off any electrode) as your origin. For example, Cz is a good selection, the most lower left grid is also a good selection.
Use a ruler (or count the grid) to measure the x and y location from the origin.
Assign your channel names to chan_nam variable, and assign x and y location to chan_loc variable (x is at left, and y is at right). The rows of chan_nam must match the rows of chan_loc variable, which stand for the channels. Like this:

chan_nam=[

'Fp1'

'Fp2'

'F7 '

'F3 '

'Fz '

'F4 '

'F8 '

'T7 '

'C3 '

'Cz '

'C4 '

'T8 '

'P7 '

'P3 '

'Pz '

'P4 '

'P8 '

'O1 '

'O2 ' ]

chan_loc=[

-3 10

3 10

-8 6

-5 7

0 8

5 7

8 6

-10 0

-7 0

0 0

7 0

10 0

-8 -6

-5 -7

0 -8

5 -7

8 -6

-3 -10

3 -10 ]

Assume that your current directory is the one that you will save session/datamat/result file, then run:

save erp_loc_besa148 chan_loc chan_nam

Now you have your own system in Edit Channel Order window if you are under ERP/BESAThetaPhi system, and you can also pick channels that is used in the ERP data. Here, obviously, the ERP/BESAThetaPhi is now representing your own system instead of the ERP/BESAThetaPhi system in PLSgui program. If you want to restore the original ERP/BESAThetaPhi system from PLSgui program, simply remove erp_loc_basa148.mat from your current directory.

5.4. Creating ERP datamat file and ERP data file

ERP module is very different from the others. Since its data is very small, you can put all subjects with all conditions into one file, which we call it ERP data file. Then you can have several ERP datamat files point to one ERP data file, and each of those ERP datamat file is part (or all) of the ERP data. ERP data is generated at the same time when you create ERP datamat.

In ERP session window, click Create Datamat button and it opens Create Datamat window (Figure 7).

Figure 7

In this window, you can deselect Channels, Subjects and Conditions. The Select All button below let you easily reset to be all selected.

Edit Channel Order here can also let you modify the channel name, but we suggest that you had better to do it in the session window, since any change here will not be saved in the session file.

Click Merge Conditions button to combine two or more conditions together to a new condition by averaging them.

You can also specify time-points range for ERP datamat, which must be within Prestim Baseline and End of Epoch.

Now, click Create button to generate ERP datamat file and ERP data file.

5.5. Modifying ERP datamat file and saving to a different name

In ERP session window, click Modify Datamat button, and select an ERP datamat file that you are going to modify. The Modify Datamat window opens with ERP Amplitude plot window. As you can see that ERP Modify Datamat window is very close to ERP Create Datamat window. There are only two differences, which are:

We removed Merge Conditions button, since you cannot modify ERP datamat file to change ERP data file.
We added Save Datamat As field. This way, we only need to create a single ERP datamat file, and then modify it (e.g. select different subjects etc.) and save it to a different ERP datamat file name.

Click Modify button to save the modified datamat file, and ERP Amplitude plot will immediately reflect the new datamat file.

5.6. Creating E.R.fMRI session file

In the PLSgui start window, click E.R.fMRI button and the button will be highlighted. Then click Session Profile for E.R.fMRI data button below, the session window will open (Figure 8).

Figure 8

In this window, Session Description field is an optional, and it reminds you what this session is for.

Datamat Prefix is used to compose a file name for datamat file. For example, if you put demo in this field, the datamat file name will become demo_fMRIdatamat.mat.

Datamat can be merged across all runs or within each run only. If Across All Runs is selected (by default), data will be averaged together across all runs for the same condition names. If Within Each Runs is selected, the same condition name in different runs will be treated as different conditions. So the actual conditions will be automatically expand to something like Run1Cond1, Run1Cond2, Run2Cond1, etc.

Click Edit Conditions button, and add condition names one by one into the Edit Condition window. Besides Condition Name field, there are two more fields: Relative Ref. Scan Onset and Number of Reference Scans. They are only used if you select Normalize data with ref. scans check box in Generate ST Datamat window. Relative Ref. Scan Onset refers the offset of the first reference scan from the first scan of each onset. Negative value means that reference scan starts before the first scan of each onset. By default, it is 0. Number of Reference Scans means how many scans after the first reference scan will be averaged together to become a reference scan. By default, it is 1, which means that only 1 scan is used for reference scan. When you click DONE, Number of Conditions will show how many conditions you selected.

Number of Runs field must be entered first before click Edit Runs. It indicates how many runs of data you have, and each run of data must be kept in a separate directory.

Click Edit Runs button to open Run Information window (Figure 9):

Figure 9

Number of Scans field must be specified first in this window.
If Number of scans to be skipped is not 0, the first several scans in this run to be skipped should not be included in the Data Files, and Number of Scans should reflects the actual number of un-skipped scans. The onset number in the fields below still starts from the very first scan of this run. If the onsets that you entered are within the skipped scans, they will be excluded when the datamat is created.
Click Browse to open Select Data Files window. Once click DONE in Select Data Files window, Data Directory field and Data Files field in the Run Information window are both filled.
Fill Onsets fields condition by condition. Please be aware that the scan starts from 0, and unit is TR or scan, not second. i.e. If you put number 10, it refers the 11th scan image you selected.
If you have many onset numbers in a field, we suggest you to prepare them in text files. One text file for each run, each line stands for a condition, and all onsets for that condition are separated by a space and listed on that condition line. Click Load Onsets from a text file for this run under Edit menu to let the program fill onsets for you. Click Save Onsets to a text file for this run will save the current filled number to a text file.
If Replicate trial information across run is selected (by default), the onset number will stay the same while you traverse from run to run.
If you decide to completely drop this run, you can click Delete under Edit menu to delete this run.

Click >> button to go to next run, and repeat the steps above for all the runs.

5.7. Creating E.R.fMRI datamat file

In E.R.fMRI session window, click Create ST Datamat button to open Generate ST Datamat window (Figure 10).

Figure 10

There are two ways to define fMRI brain region, and they are the same as two ways to define PET brain region. Since any intensity of voxel that is less than the threshold of maximum intensity will be treated non-brain region, we require that the minimum of image intensity should be no less than 0.

Temporal window size refers to the length of hemodynamic period, and unit is TR or scan. e.g. If the length of hemodynamic period is 16 seconds and each TR is 2 seconds, then window size is 8 TRs.

If Normalize data with ref. scans is checked, datamat will be normalized by the selected ref. scans. Please be aware that by default Normalize data with ref. scans is selected for both E.R.fMRI and Blocked fMRI data to prevent huge DC offset (low frequency noise).

Single subject analysis is only used to analyze single subject with very few onsets. If this check box is selected, each onset block will be stacked as a separate volume. So, datamat will only be averaged within each onset block, rather than within each condition. In this case, the number of onsets must be the same for all conditions, since we require that the number of subjects (or onsets in this case) must be the same for all conditions.

Single reference scan will use this reference scan for all the scans in the datamat, which will replace whatever Relative Ref. Scan Onset and Number of Reference Scans that you set in the Edit Condition window. It is also only used when you select the Normalize data with ref. scans check box. In Single reference scan onset edit box below, you should enter an absolute reference scan onset, instead of a relative reference scan onset.

Now, click Create button to generate E.R.fMRI datamat file.

5.8. Creating E.R.fMRI session file with user defined HRF

In the PLSgui start window, click Blocked fMRI button and the button will be highlighted. Then click Session Profile for Blocked fMRI data button below, the session window will open (Figure 11).

Figure 11

This window is very similar to the regular E.R.fMRI session window, except that there is a check box called Use HRF instead of Blocked Length. If you check this box, your session file is for E.R.fMRI with user defined HRF; if you uncheck this box, your session file will become Blocked fMRI, which will be described below. Once you made the decision, this cannot be changed. If you really want to change, you will have to make a new session file.

Like regular E.R.fMRI session window, click Edit Runs button to open Run Information window (Figure 12):

Figure 12

This is also very similar to the regular E.R.fMRI Run Information window, except that there is one more field under Onsets, which is called Duration, and is used for epoch-related response. If your experiment is only for event-related response, just enter 0.

5.9. Creating E.R.fMRI datamat file with user defined HRF

In above session window, click Create Datamat button to open Generate Datamat window (Figure 13).

Figure 13

The Brain Region section is exactly the same as the regular E.R.fMRI, but the Datamat section is completely different.

If Use SPM ReML is checked, you are using the feature that is copied from SPM to remove the voxel outliers over the run. It is a temporal whitening function using restricted maximum likelihood estimation.

Degree of Legendre Polynomials for regressors is used to define the baseline regressor(s). By default, it is 0, which provides a single column of all ones.

You must enter the length of TR (in seconds) in order to define the HRF.

Then, you have two options to define the HRF: HRF1 & HRF1. For HRF1, TR will be further divided when calculating design matrix. By default, it will use HRF model from SPM, since most codes are copied from SPM. For HRF2, TR is always the smallest unit when calculating design matrix. By default, it will use GAMMA HRF from AFNI. In both case, you can click Customize HRF to modify the model, and click Save HRF to save the model.

When you click Plot Regressors, the entire hemodynamic response across the run will be displayed. This is actually the convolution result between HRF and event (or epoch), which is sometimes also called design matrix.

Now, click Create button to generate E.R.fMRI datamat file with user defined HRF.

5.10. Creating Blocked fMRI session file

Creating Blocked fMRI session file is almost the same as Creating E.R.fMRI session file with user defined HRF. However, don’t check Use HRF instead of Blocked Length check box, which is for E.R.fMRI with user defined HRF.

5.11. Creating Blocked fMRI datamat file

Creating Blocked fMRI datamat file is the same as creating E.R.fMRI datamat file, except that you do not need to fill Temporal window size field for Blocked fMRI datamat.

5.12. Creating Structural MRI session file

In the PLSgui start window, click Structural button and the button will be highlighted. Then click Session Profile for Structural data button below, the session window will open (Figure 14).

Figure 14

In the session window, Session Description is an optional field, which reminds you what this session is for.

Datamat Prefix is used to compose file names for Structural datamat file and Structural data file. For example, if you put demo in this field, demo_STRUCTdatamat.mat will be Structural datamat file name and demo_STRUCTdata.mat will be Structural data file name.

Dataset Directory is where all subjects with all conditions are kept.

Click Input Conditions button, and add condition names one by one into the Edit Condition window (Figure 15). Besides Condition Name field, there is one more field: Condition Filter. You must enter wildcard (e.g. *wm.nii) to distinguish files with different conditions. When you click DONE, Number of Conditions will show how many conditions you have selected.

Figure 15

Click Select Subjects button, and Edit Subject Directory window will open (Figure 3). Now, click Add button, and Subject Directory Detail window will open (Figure 16). You can select one or more subjects for this datamat group. By default, the program will use the filename without condition filter part as the subject name. If you feel that the subject name is too long, you can change the subject name in the Edit Subject Directory window.

Figure 16

5.13. Creating Structural MRI datamat file and data file

Like ERP module, you can put all subjects with all conditions into one file, which we call it Structural data file. Then you can have several Structural datamat files point to one Structural data file, and each of those Structural datamat file is part (or all) of this Structural data. Structural data is generated at the same time when you create Structural datamat.

In Structural session window, click Create Datamat button and it opens Create Datamat window (Figure 17).

Figure 17

In this window, you can deselect the subjects. The Select All Subjects button below let you easily reset it to be all selected.

In Brain Mask File field, you must provide a pre-defined brain region image file.

Now, click Create button to generate Structural datamat file and Structural data file.

5.14. Modifying Structural MRI datamat file and saving to a different name

In Structural session window, click Modify Datamat button, and select a Structural datamat file that you are going to modify. The Modify Datamat window opens. As you can see that Modify Structural Datamat window is very close to Create Structural Datamat window. There are only three differences, which are:

We removed Brain Mask File field, since you cannot modify Structural datamat file to change Structural data file.
For the same reason, we removed Check image orientation button.
We added Save Datamat As field. This way, we only need to create a single Structural datamat file, and then modify it (e.g. select different subjects etc.) and save it to a different Structural datamat file name.

Click Modify button to save the modified datamat file.

6. Running PLS analysis

The purpose of performing PLS analysis on neuroimaging data is to obtain result data that can better interpret the brain activities and other brain statistical information, which can include singular values, singular vectors, etc. The internal procedures of an analysis includes:

Stack datamat in the format of subject within condition within group. For Behavior PLS and Multiblock PLS, behavior data should also be stacked in this way.
Generate a covariance or correlation matrix from the stacked datamat (and stacked behavior data).
Decompose the covariance or correlation matrix to compute the singular vectors.
Run permutation for significance test (optional).
Run bootstrap for reliability test (optional).

In the PLSgui start window, select a module and then click Run PLS Analysis button below, the analysis window will open (Figure 18).

Figure 18

The PLS analysis window is almost identical across all modules. However, there are still some slight differences. e.g. For PET, ERP and Structural module, each group only contains one file, and it is datamat file. For E.R.fMRI and Blocked fMRI module, each group can contain more than one file, and they are session files. Each session file should correspond a datamat file.

In the analysis window, group files must be added first. For PET, ERP and Structural module, click Add button to select a datamat file for each group. For E.R.fMRI and Blocked fMRI module, click Add button will open a Select Session Profiles window (Figure 19) for a group.

Figure 19

Highlight E.R.fMRI and Blocked fMRI session files for this group, and click >> button to add them into the right panel. You can save this selection by clicking Save to a text file under File menu of Select Session Profiles window. Next time, you do not need to select session files again. You can click Load from a text file under File menu of this window, and those selections you selected will be loaded in the window.

The Group Total in PLS analysis window will display how many groups you selected. The Save Datamats check box is only selected if you want to save the stacked datamat. We advise regular users not to select this check box, since it will make result file huge. After all group files are added, you also have an option to remove some conditions by clicking Deselect conditions under Deselect menu. You do not have to do this unless it is necessary.

Now you have to select one of the PLS options:

If you choose Mean-Centering Task PLS option, the grand mean across tasks is calculated, and all individual data points are subtracted from this value. The newly generated matrix is subjected to singular value decomposition (SVD) to obtain singular values, singular vectors, etc.

If you choose Non-Rotated Task PLS option, priori contrasts are used to restrict the patterns derived from PLS. So you also need to provide a contrast file (in plain text) in order to run this analysis. Click Load button beside Contrast Data File field to select a contrast file. Contrast file can be generated from the Contrast window (Figure 20) by clicking Contrast menu in the analysis window.

Figure 20

In the contrast window, field Contrast 1 stands for 1st contrast, and field Contrast 2 stands for 2nd contrast, etc. The 1st value in each contrast field is for the 1st selected condition, and the 2nd one is for the 2nd selected condition, etc. Click Add button beside contrast field to input the contrast value, and lick Plot button to display bar graph of this contrast. If you have more than 1 group, you also have to fill all contrast fields for all groups. Highlight different group name in Groups panel to switch groups. Finally, Don't forget to save contrasts to a text file for PLS to load.

For Regular Behav PLS, Non-Rotated Behav PLS or Multiblock PLS, you must have at least 3 subjects in order to generate proper correlation matrix and run PLS properly.

If you choose Regular Behav PLS option, behavior measures that correspond to each scan image or ERP data are used to compute the correlation matrix between the measures and the datamat. So you also need to provide a behavior file (in plain text) in order to run this analysis. Each column in the behavior file stands for one measure, and is separated by a space. The rows should be arranged in the order of “subjects in selected conditions in groups”.

For example, let's say you have group1 and group2 with condition1, and condition2. In group1, you have 2 subjects, and in group2 you have 3 subjects. Here is the order of the behavior file:

group1 condition1 subject1

group1 condition1 subject2

group1 condition2 subject1

group1 condition2 subject2

group2 condition1 subject1

group2 condition1 subject2

group2 condition1 subject3

group2 condition2 subject1

group2 condition2 subject2

group2 condition2 subject3

To input behavior data for PLSgui, click Load behavior data button, and the Edit Behavior Data window will open (Figure 21).

Figure 21

In this window, click Load button and select a behavior file we discussed above. You should see all the data in behavior file has been loaded into the Behavior Data text editor. You can then change Behavior name to some meaningful string like RT ACC etc. Click OK button when finish. If you deselect any condition after loading behavior data, you have to click Load behavior data button again. This is because the behavior data should correspond to the selected conditions only.

If you choose Non-Rotated Behav PLS option, priori contrasts are used to restrict the patterns derived from PLS, as well as behavior measures that correspond to each scan image or ERP data that are used to compute the correlation matrix between the measures and the datamat. So you need to provide both contrast file and behavior file (both are in plain text) in order to run this analysis. If you have more than one behavior measure (i.e. behavior file has more than one column), you will also need to provide contrast for all the behavior measures.

For example, let's say you have group1 and group2 with condition1, and condition2, and you have two behavior measures in behavior file. Here is the order of the contrast file:

group1 condition1 measure1

group1 condition1 measure2

group1 condition2 measure1

group1 condition2 measure2

group2 condition1 measure1

group2 condition1 measure2

group2 condition2 measure1

group2 condition2 measure2

If you choose Multiblock PLS option, the program will apply both Mean-Centering Task PLS and Regular Behav PLS to the same datamat. So, a behavior file is required, and is input the same way as Regular Behav PLS does. You can also choose to select only part of conditions for behavior block of Multiblock PLS. To do this, you need to click Deselect behaviorblock conditions for Multiblock PLS under Deselect menu. You do not have to do this unless it is necessary.

You also have opportunities to input number of permutation to test the significance of the singular vectors and input number of bootstrap to test the reliability of the activity area. However, make sure you have enough subjects. Otherwise, it does not make sense to reorder data. This is especially important in bootstrap test, because we reorder bootstrap data with replacement and it contains repeated subjects after reordering. If you choose bootstrap test, the bootstrap result will also contain the upper and lower percentile of correlations. It is determined by the value in Confidence Level field, which is 95 percent by default.

Click Run button to run PLS analysis, and you will need to input a result file name first. If you would like to include bootstrap test, a dialog box of Percentage of minimum different subject number will be prompted with a default value of 50 percent. This is because bootstrap test may contain repeated subjects after data is reordered, and we need to limit the repeat by setting a minimum different subject number. You can slightly adjust this value to include more or less repeated subjects after data is reordered.

Instead of click Run button, you can also click Save to Batch button to save the PLS analysis setting into a batch script file. Then, you can either run PLS analysis by firing the batch with batch_plsgui command, or simply use it to save your PLS analysis setting and click Load from Batch button in the future to bring up the setting.

7. Rendering Result file

This User's Guide only describes how to display a PLS result file. If you would like to know how to interpret your result in detail, please read relevant papers.

7.1. Displaying PET result file

In the PLSgui 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 should do so in the Create PET Datamat window.

If the crosshair bothers you, you can turn it off or change its color under Crosshair menu. You can click Zoom on 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 in Windows menu.

7.1.1. Singular Values Plot

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 the 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 chance of permuted singular values that are greater than the observed singular values are very high for certain LVs, you may also want to discard those LVs.

7.1.2. Voxel Intensity Response

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 of the brain in result window, voxel value in the location that is specified by XYZ will be plotted (Figure 24).

Figure 24

Different subjects can be distinguished by legend mark. Subject average for each condition is provided in 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 unnecessary 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.

7.1.3. Multiple Voxels Extraction

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).

7.1.4. Design LV and Design Scores Plot

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 you have more than one group, highlight the group that you would like to watch in the upper left panel. If the result has more than one LV, highlight the LV that you would like to watch in the lower 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. The task patterns in Design Scores (or Design LVs) correspond to each task in BrainLV active map for each LV.

7.1.5. Task PLS Brain Scores with CI

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.

7.1.6. Brain Scores vs. Behavior Data Plot

Click 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 selection box. If the result has more than one LV, select the LV radio button that you would like to watch in the 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

For Regular Behav PLS, the Behavior LV bars should be in proportion with Correlation bars.

Click Show Correlation Plot under Plot menu will display a correlation bar. It reflects the correlations between behavior data and brain scores for each condition and each LV. If bootstrap test is included, correlation bar will come with an error bar specified by 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 (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

7.1.7. Datamat Correlations Response

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

7.1.8. Datamat Correlations Plot

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 a whole view of the correlation values in the entire brain for each condition and each behavior measure (Figure 32).

Figure 32

Instead of selecting the group from a selection box, you enter the group ID, which is ordered sequentially, into the Group Index field. Parameters in the Datamat Correlations 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 corresponds to its color that can be referred from the marks on the color bar.

Besides the Axial View that the result window renders by default, you can also select Sagittal View, Coronal View, and 3 Cardinal Plane View under Windows menu.

7.1.9. Cluster Report

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 as 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 cluster 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 (MNI location), 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.

7.1.10. File menu

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. Usually, brain template image could be an image that is used to register the brain for all images in the 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.

7.2. Displaying Structural MRI result file

The way to display a Structural MRI result file is the same as the way to display a PET result file.

7.3. Displaying Blocked fMRI result file

The way to display a Blocked fMRI result file is the same as the way to display a PET result file.

7.4. Displaying E.R.fMRI 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:

7.4.1. Different slices layout in result window

E.R.fMRI displays all lags of temporal window in its result window (Figure 34).

Figure 34

Lag stands for which scan in the temporal window. It is started 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, and all slices are displayed in the display area row by row (like montage).

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.

7.4.2. Response Function Plot vs. Voxel Intensity Response

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 a 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.

7.4.3. Temporal Brain Scores Plot

For Mean-Centering PLS, Non-Rotated Task PLS, or Multiblock PLS, there is a new 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.

7.4.4. Temporal Brain Correlation Plot

For Behavior PLS or Multiblock PLS, there is also a new 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.

7.4.5. Different Datamat Correlations Response 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 of the brain in result window, correlation value for the entire temporal window at XYZ will be plotted.

7.5. Displaying ERP result file

The way to display an ERP result file is much different from the way to display a Blocked fMRI, E.R.fMRI, or a PET result file.

In the PLSgui start window, click ERP button and the button will be highlighted. Then click Show PLS Result for ERP data button below, you will be asked to select a result file. Once you have selected the result file, the 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 on any waveform, an pink information box that contains channel name and wave name will be popped up.

Figure 36

7.5.1. TOOL menu

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.

7.5.2. LEGEND menu

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.

7.5.3. ZOOM menu

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.

7.5.4. EDIT 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 some bad subjects and/or electrodes in ERP Amplitude window immediately after creating ERP datamate. In ERP Amplitude window, you can select a bad subject by clicking on the bad subject waveform, and select bad electrodes by clicking their names and making them bold. Then click Modify Datamat under Edit menu, the Modify Datamat window opens, and the selected subject and all selected electrodes are preliminary un-highlighted. Once you click Modify button in Modify Datamat window, the bad subject and electrodes will be removed from the datamat file.

7.5.5. VIEW menu

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.

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, an pink information box that contains wave name, channel name, X & Y locations will be popped up at upper right corner.

Figure 37

Subject Amplitude for Given Timepoints

It looks like Plot Detail window (Figure 37) 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 (Figure 24).

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.

8. Seed PLS Analysis

We can use correlation between datamat value from a detected voxel and entire brain datamat to run Regular Behav PLS analysis, and call it Seed Voxel PLS analysis.

8.1. Step-by-Step Procedures

Open a PET, E.R.fMRI or Blocked fMRI result file to the result window, and search for seed voxels.
Write down their XYZmm positions (must be voxel location with unit in millimeter, not absolute voxel location). In order to avoid out of memory problem, please choose only a few positions (How few it should be will depend on the size of your datamat). For E.R.fMRI, don't worry about lags, since all lags in temporal window will be extracted.
Click Multiple Voxel Extraction under Windows menu to do Multiple Voxel Extraction for above voxels, and it will generate two kinds of files below. However, we only use Format A file, which includes all subjects in all groups:

Format A: PREFIX_MODULEvoxeldata.txt (only 1 file)

(This one includes all subjects in all groups)

Format B: PREFIX_MODULE_grp_[subj]_voxeldata.txt

(Each of these files will correspond to each session/datamat pair.)

Start Run PLS Analysis window. Add the same datamats and select the same conditions as you did to create the above result file.
Choose Regular Behav PLS option. Click Load behavior data button, and load the behavior data in format A (including all subjects in all groups). For E.R.fMRI, if there is any column (specified by Behavior Name) containing Behavior Data value of 0 across all rows in Edit Behavior Data window, it is a baseline lag and should be removed.
Enter the number of Permutation / Bootstrap (optional), and click Run to run Seed Voxel PLS Analysis.

9. Batch Process

Instead of using mouse click, messages can also be loaded from a batch script file and sent automatically to PLSgui program in batch with batch_plsgui command. The first advantage of the batch process is that it dramatically reduces the Human-Computer Interactions. So, you can fire batches at the end of a day, and the computer will create all datamats one by one and run all analysis for you. When you come back next day, the PLS result file(s) is ready for you to display. The second advantage is that it is very easy to modify the batch script file to re-run the analysis with or without re-create the datamat. The third advantage is that the session files, datamat files, and result files that are generated by batch_plsgui are fully compatible with those that are generated by PLSgui, since batch_plsgui command is part of PLSgui program and is actually running PLSgui in batch. The disadvantage is that batch script files must be checked carefully, especially when firing batches to run overnight.

There is a completely different program called PLScmd, which is basically a command-line version of PLS. PLScmd program is totally separate from PLSgui, and they are not compatible each other. PLScmd will be introduced in Appendix B.

9.1. How to write a batch script file

In order to create datamats or run analyses in batch, you will first need to prepare corresponding batch script files. Batch script files are simply text files, and we will discuss them in detail in the following sections.

Coming with PLSgui program, you will find several demo batch scripts:

batch_demo_fmri_data1.txt % batch file to create E.R.fMRI datamat

batch_demo_fmri_data2.txt % batch file to create E.R.fMRI datamat

batch_demo_fmri_data3.txt % batch file to create E.R.fMRI datamat

batch_demo_fmri_analysis.txt % batch file to run E.R.fMRI PLS analysis

batch_demo_bfm_data1.txt % batch file to create Blocked fMRI datamat

batch_demo_bfm_data2.txt % batch file to create Blocked fMRI datamat

batch_demo_bfm_data3.txt % batch file to create Blocked fMRI datamat

batch_demo_bfm_analysis.txt % batch file to run Blocked fMRI PLS analysis

batch_demo_erp_data1.txt % batch file to create ERP datamat

batch_demo_erp_data2.txt % batch file to create ERP datamat

batch_demo_erp_analysis.txt % batch file to run ERP PLS analysis

batch_demo_pet_data1.txt % batch file to create PET datamat

batch_demo_pet_data2.txt % batch file to create PET datamat

batch_demo_pet_analysis.txt % batch file to run PET PLS analysis

Once you follow the instructions discussed in the following sections and create your own batch scripts, you can run batch script files using batch_plsgui command.

You can run several batch scripts from one batch call. The following command will create an ERP datamat, and run ERP analysis using the created datamat:

batch_plsgui batch_demo_erp_data1.txt batch_demo_erp_analysis.txt

You can also streamline the batch processing by putting multiple batch calls in one M file. The following will create three fMRI datamat files, and run fMRI PLS analysis that will use these three fMRI datamat files:

batch_plsgui batch_demo_fmri_data1.txt

batch_plsgui batch_demo_fmri_data2.txt

batch_plsgui batch_demo_fmri_data3.txt

batch_plsgui batch_demo_fmri_analysis.txt

The easiest way to get started is to copy a demo batch script file that come with PLSgui program, and then modify it according to your situation:

Go to PLSgui program folder. If you don't know where is PLSgui program folder, you can type which plsgui under MATLAB command window to find the location of PLSgui program folder.
Search for batch_demo_MODULE* for MODULE related batch. e.g. batch_demo_erp* is for ERP related batch. batch_demo_erp_data1.txt is for creating ERP datamat; batch_demo_erp_analysis.txt is for running ERP PLS analysis.
Copy all corresponding batch files from PLSgui program folder to your working folder where you save all files, and go to this folder. Reminder: all files generated from PLSgui should be saved under the same folder where you start PLSgui program.
Rename the demo batch files, and edit them with the necessary changes. Sections below and comments in those batch files explain how to edit them.
Each batch file is composed of several lines. Empty line or any line using “%” as first non-blank character will not be read. Each line starts with a keyword string (e.g. prefix, num_boot etc.). These keywords should never be changed. Following the keyword is its corresponding value. You can use either tab or space to separate keyword / value or value1 / value2. At the end of value, you also have an option to append some comments that are started with “%” character.
Once you have modified (or created) batch files, you can put all batch calls into an M file, so they can be executed one after the other (see batch_demo_*.m).

9.2. Batch file to create E.R.fMRI datamat

Instead of filling the fields in the Session Information or Create Datamat window manually, we can put them as the values of keywords in a batch file (see batch_demo_fmri_data1.txt):

Value of prefix keyword is a string (e.g. demo) that will compose session and datamat file name (e.g. demo_fMRIsession.mat and demo_fMRIdatamat.mat).
Value of brain_region keyword can be either a threshold number or a file name with path info that indicates the brain region binary file.
Value of win_size keyword indicates the number of scans in one hemodynamic period.
Value of across_run keyword can be either 1 or 0. Use 1 for merging data across all run for each condition, and use 0 for merging data within each run and then stacked together run by run.
Value of single_subj keyword refers to a new feature that does not average all onsets in a condition. To use this feature, set it to 1, and scans that are led by each onset will be treated as an individual block in the datamat. Otherwise, scans for all the onsets will be averaged together as one block.
Value of single_ref_scan keyword refers to a new feature that will replace the ref_scan_onset keyword and num_ref_scan keyword below. To use this feature, set it to 1, and all scans in this datamat will use this reference scan.
Value of single_ref_onset keyword is the onset for single_ref_scan keyword above, and starting from 0.
Value of single_ref_number keyword is the number of onset for single_ref_scan keyword above, and starting from 1.
Value of the first cond_name keyword is name of condition1, and the name of condition2 is listed after condition1 in sequence for value of the second cond_name keyword.
Value of the first ref_scan_onset keyword is the reference scan onset for condition1, and the one for condition2 is listed afterwards in sequence for value of the second ref_scan_onset keyword.
Value of the first num_ref_scan keyword is the number of reference scans for condition1, and the one for condition2 is listed afterwards in sequence for value of the second num_ref_scan keyword.
You can re-organize them to let cond_name, ref_scan_onset, and num_ref_scan be grouped together (see batch_fmri_data1.txt). However, sequence should not be changed (i.e. name for condition2 can not be listed before name for condition1). The same rule is also applied to ref_scan_onset & num_ref_scan in condition section and data_files & event_onsets in run section.
Value of the first data_files keyword stands for all selected file names of scan images in run1 with path information. All selected image file names in the run directory should be sorted in alphabetic ascend order that represent scans of this run in time series sequence. Wildcard must be used for all selected file names. Run2 is listed after run1 in sequence for value of the second data_files keyword.
Values of the first event_onsets keyword stand for the onset scans (start from 0) of condition1 in run1. Then, condition2 in run1 for values of the second event_onsets keyword ... etc. So the sequence should always be condition in run.

9.3. Batch file to run E.R.fMRI analysis

Instead of filling the fields in the Run PLS Analysis window manually, we can put them in a batch file (see batch_ demo_fmri_analysis.txt):

Value of result_file keyword is a string for result file name with path information. It must be listed first in the analysis batch file.
Values of the first group_files keyword stand for all session file names for group1. (In E.R.fMRI or Blocked fMRI, each group can contain more than one session file, and each session file can have more than one run). Group2 is listed after group1 in sequence for value of the second group_files keyword.
You have 5 PLS analysis option. Set value of pls keyword to 1 if you would like to do Mean-Centering PLS; set it to 2 for Non-Rotated Task PLS; set it to 3 for Regular Behav PLS; set it to 4 for Multiblock PLS; set it to 5 for Non-Rotated Behav PLS.
Value of num_perm keyword refers to number of permutations.
Value of num_boot keyword refers to number of bootstraps.
Value of clim keyword refers to confidence level of bootstrap test for Behavior (or Multiblock) PLS.
Value of save_data keyword can be either 0 or 1. Choose 1 if you would like to save the stacked datamat; choose 0 otherwise.
Leave values of selected_cond keyword commented if you do not deselect any condition. Otherwise, use only 1 or 0 for the value of each condition, where 0 stands for the deselected condition (condition for behavior block in multiblock PLS is not deselected here, and they should be deselected by selected_bcond below).
Leave values of selected_bcond keyword commented if you do not deselect any condition for behavior block in multiblock PLS. Otherwise, use only 1 or 0 for the value of each condition, where 0 stands for the deselected conditions (keyword selected_bcond is only applied to conditions for behavior block in multiblock PLS). In addition, you cannot select any conditions for selected_bcond that were deselected in selected_cond.
Values of the first contrast_data stand for the contrast data of selected condition1 in group1. Then, selected condition2 in group1 for value of the second contrast_data keyword ... etc. So the sequence is selected condition in group. Number of values for each contrast_data row should be the same, and it represents the number of contrasts.
Values of the first behavior_data stand for the behavior data of session1 of selected_condition1 of run1 of group1. The sequence should always be session-in-selected_condition-in-run-in-group. Number of values on each behavior_data row should be the same, and it represents the number of behavior measures.

9.4. Batch file to create Blocked fMRI datamat

It is very similar to Batch file to create E.R.fMRI datamat. Here are some differences:

No win_size keyword for Blocked fMRI.
event_onsets keyword is replaced by block_onsets.
New block_length keyword is used after each block_onsets to represents the number of scans for each block.

9.5. Batch file to run Blocked fMRI analysis

It is very similar to Batch file to run E.R.fMRI analysis. The only difference would be that all the file names containing fMRI are now replaced by BfMRI.

9.6. Batch file to create ERP datamat

ERP datamat is very different from that of E.R.fMRI or Blocked fMRI, since a lot of EEG/ERP parameters have to be added in:

Value of prefix keyword is a string (e.g. demo) that will compose session and datamat file name (e.g. demp_ERPsession.mat, demo_ERPdatamat.mat, and demo_ERPdata.mat).
Value of prestim keyword stands for the number of milliseconds for prestimulus baseline.
Value of interval keyword stands for the number of milliseconds for digitization interval.
Values of chan_order keyword are indices for electrode channels. The best way to obtain them is run MATLAB command:

[chan_order, system] = erp_select_chan

Value of system_class keyword takes structure variable value system.class that was obtained together with chan_order.
Value of system_type keyword takes structure variable value system.type that was obtained together with chan_order.
If your data are in plain text file, leave binary_vendor keyword commented or put none for its value. Otherwise, fill the value of binary_vendor keyword with the name of binary data vendor. They can be NeuroScan, ANT, and EGI.
If your data are in plain text file, leave binary_endian keyword commented, or put none for its value. Otherwise, fill the value of binary_endian keyword with a proper MATLAB machine format, they can be: ieee-le or l, ieee-be or b, ieee-le.l64 or a, ieee-be.l64 or s, vaxd or d, vaxg or g, cray or c, and native or n.
Value of the first cond_name keyword is name of condition1, and the name of condition2 is listed after condition1 in sequence for value of the second cond_name keyword.
All binary data and most plain text data are laid out in a way that each row represents an electrode channel. However, there are a few plain text data that are laid out in a way that each column represents an electrode channel. In the latter case, set the value of chan_in_col keyword to 1.
Value of the first subj_file keyword stands for ERP data file name with path information for subject 1 in condition 1. Then, subject 2 in condition 1 for value of the second subj_file keyword ... etc. So the sequence should always be subject in condition.

9.7. Batch file to run ERP analysis

It is very similar to Batch file to run E.R.fMRI or Blocked fMRI analysis. Here are the differences:

All file names that contain fMRI or BfMRI are now replaced by ERP.
ERP and PET modules use datamat file name for the value of group_files keyword, while fMRI and BfMRI use session file name(s).
ERP and PET modules use only one datamat file for each group_files keyword, while fMRI and BfMRI can use more session file names.
The sequences should be subject-in-selected_condition-in-group for the value of behavior_data keyword.

9.8. Batch file to create PET datamat

It is very similar to Batch file to create ERP datamat. Since PET does not use any of EEG/ERP parameters, those keywords can all be removed except prefix, cond_name, and subj_file. However, brain_region keyword needs to be added in, and its value can be either a threshold number or a file name with path information that indicates the brain region binary file.

9.9. Batch file to run PET analysis

It is very similar to Batch file to run ERP analysis. The only difference would be that all the file names containing ERP are now replaced by PET.

9.10. Batch file to create Structural datamat

It is very similar to Batch file to create PET datamat. Here are the differences:

Since Structural datamat module cannot use threshold, a pre-defined brain region image file must be used for brain_region keyword.
Value of dataset_path keyword is a string that represents subject files' folder.
Value of normalize keyword is used for Normalize Volume Mean option. It should be kept as 0 (default), unless you have good reason to change it to 1 (means that you want to do volume normalization).
Value of cond_filter keyword is a string of wildcard to distinguish different conditions.
Value of subj_name keyword is a string of subject's name.
Value of subj_file keyword is just the subject's file name, and does not need to include its path.

9.11. Batch file to run Structural analysis

It is very similar to Batch file to run ERP analysis. The only difference would be that all the file names containing ERP are now replaced by STRUCT.

10. Appendix

10.1. Appendix A: Example Data Sets

The subjects' data below is only for the purpose of illustration the usage of PLS program:

http://www.rotman-baycrest.on.ca/pls/source/Testdata.zip

After unzip the above data, go to the testdata folder and launch MATLAB from there. Add path to access the PLSgui program, and follow the instructions below for the experiments.

10.1.1. PET Experiment

In this experiment, datamat has been created and result file has been generated. By loading the session file and result file, we can see the information that have been entered into the session file, and some meaning from the result file. Since you do not have subjects' raw data (image file) for this experiment, you cannot modify anything.

There are 12 subjects with 8 conditions in this experiment. Click Session Profile for PET data under PLS start window, and load “pet_PETsession.mat” file. Click Input Conditions button to see what are the 8 conditions, and click Select Subjects button to see what are the 12 subjects. Close the Session Information window, 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 the 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.

10.1.2. fMRI Experiment

In this experiment, you only have one subject's data. You can follow the steps below to see how to create session file, generate datamat file, and run PLS analysis to get the 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 session file:

Click E.R.fMRI button in PLSgui start window, and click Session Profile for fMRI data button, the fMRI session window will open.
Type E.R.fMRI Experiment on test data in Session Description field.
Type test in Datamat Prefix field.
Leave Across All Runs for Merge Data field.
Click Edit Conditions button, and Edit Condition window will open.
Type Task1 for condition1 field under Condition Name column, and click Add button.
When condition2 field shows up, type Task2 for condition2 and click Add button.
For condition3, type in Baseline in the field.
Now, click DONE button to close the Edit Condition window, and you will find the value of Number of Conditions field becomes 3.
Type 5 in Number of Runs field, and click Edit Runs button beside it, a Run Information window will open.
Type 180 in Number of Scans field, and click Browse button to open Select Data Files window.
Click dataset_001 in the Directories panel and click Select All button.
Click DONE button to close the Select Data Files window.
Click Load Onsets from a text file under Edit menu, and select onsets.txt file.
Keep Replicate trial information across run check box selected, and click >> button to proceed to the second run.
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.
Click Browse button like you did in the first run, and open Select Data Files window.
Click dataset_002 in the Directories panel and click Select All button.
Click DONE button to close the Select Data Files window.
Click >> button to proceed to the next run, and repeat the above steps for all 5 runs.
Click DONE button to close the Run Information window.
Click Save under File menu to save the session file to test_fMRIsession.mat file name, and the program will remind you not to change file name manually in MATLAB command window. Click OK to dismiss this dialog box.

You can now generate a datamat file that corresponds to this session file:

Click Create ST Datamat button, and the program will open a Generate ST Datamat window.
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.
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 session file and datamat file. Usually, you should have more than 1 subject for PLS analysis, and each subject will have 1 session file and 1 datamat file. This is especially required for permutation or bootstrap test. Here we only have 1 subject for illustration purpose, so the following step will run Mean-Centering PLS without permutation or bootstrap test:

Click E.R.fMRI button in PLSgui start window, and click Run PLS Analysis on fMRI data button, the PLS Analysis window will open.
Click Add button to open Select Session Profile Window.
Highlight test_fMRIsession.mat file name, and click >> button in the middle. Then click DONE to close Select Session Profile Window.
Click Mean-Centering PLS button as PLS option.
Leave Number of Permutation and Number of Bootstrap as 0, since we only have 1 subject.
After you click Run button, the program will prompt you to enter the result file name. You can either select a new result file name, or simply use the default one test_fMRIresult.mat as file name.
Once PLS analysis is done, it goes back to the start window.
In order to view the result data, you need to click E.R.fMRI button in PLSgui start window, and click Show PLS Result for fMRI data button. The program will prompt you to select a result file name, and you can select test_fMRIresult.mat to display this result file.

10.2. Appendix B: Command-Line PLS

As is mentioned earlier, the command-line PLS (PLScmd) is a separate program that is not compatible with PLSgui. The command to run PLS analysis is pls_analysis. Compared with PLSgui, pls_analysis is easier to understand, because there is no fancy data stacking or result rendering issues. In order to run pls_analysis, the following input variables must be assigned properly for its pls_analysis command:

datamat_lst: This is a datamat cell array. Each cell stands for one datamat, which is also referred as a group. The rows of datamat must be in the order of “subject in condition”.
num_subj_lst: This is an array that contains the number of subjects in each group. e.g.: [4 5 7] stands for 3 groups. The first group has 4 subjects; the second one has 5 subjects, and the third one has 7 subjects.
num_cond: This is the number of conditions for the analysis. e.g.: 3 means 3 conditions.

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)

The output result is a structure variable that contains all the necessary items that are generated based on different PLS options that will be asked when running pls_analysis command. 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
origpost: posthoc result, only available in behavior PLS, when posthoc file is provided
perm_result: struct containing permutation result

num_perm: number of permutation
sp: permuted singular value greater than observed
sprob: sp normalized by num_perm

boot_result: struct containing bootstrap result

num_boot: number of bootstrap
bootsamp: bootstrap reorder sample
orig_u: original salience (orig_u = u * s)
orig_v: original designlv or original behavlv
compare_u: compared salience or compared brain
compare_v: compared designlv or compared behavlv
u_se: standard error of salience or brainlv
v_se: standard error of designlv or behavlv
distrib: orig_usc or orig_corr distribution
prop: orig_usc or orig_corr probability
orig_usc: same as usc, only available in task PLS
ulusc: upper boundary of orig_usc, only available in task PLS
llusc: lower boundary of orig_usc, only available in task PLS
ulusc_adj: percentile of orig_usc distribution with upper boundary of orig_usc, only available in task PLS
llusc_adj: percentile of orig_usc distribution with lower boundary of orig_usc, only available in task PLS
orig_corr: same as lvcorrs, only available in behavior PLS
ulcorr: upper boundary of orig_corr, only available in behavior PLS
llcorr: lower boundary of orig_corr, only available in behavior PLS
ulcorr_adj: percentile of orig_corr distribution with upper boundary of orig_corr, only available in behavior PLS
llcorr_adj: percentile of orig_corr distribution with lower boundary of orig_corr, only available in behavior PLS

o num_LowVariability_behav_boots: display numbers of low variability re-sampled behavior data in bootstrap test, only available in behavior PLS

badbeh: display bad behav data that is caused by bad re-order (with 0 standard deviation) which will further cause divided by 0, only available in behavior PLS

o countnewtotal: count the new sample that is re-ordered for badbeh, only available in behavior PLS

Since the result generated by pls_analysis is not compatible with PLSgui and can not be displayed on PLSgui, it can only be interpreted by the advanced users. However, you may find the following simple guidelines helpful:

Usually, the first thing to be checked is singular value, and the percentage of eigenvalue. If the percentage is very low for certain LVs, simply discard those LVs:

figure; bar(result.s); % display singular value bar graph

pct=(result.s.^2/sum(result.s.^2)); % calculate eigenvalue percentage

figure; bar(pct); % notice that sum(pct) should be 1

If permutation loop is applied, you can also check whether those LVs can be trust by plot bar graph of the probability of permuted values greater than observed values. If for certain LVs, the chance of permuted values greater than observed values are very large, you also need to discard those LVs:

figure; bar(result.perm_result.sprob);

Next, for Task PLS, the outlier subjects should be checked for each meaningful LV. If there is any outlier subjects, you may want to reconsider if you want to keep them or remove them. If you decide to remove them, you will have to run analysis again without those subjects:

LV = 1; % just an example. can be 2,3, ...

figure; plot(result.vsc(:,LV),result.usc(:,LV),'*');

You also need to render the active area map "result.u" depending on whether your data is a brain image or a brain wave. If it is a brain image, you must have a brain coordinates and dimensions handy. Simply create a brain and put the result.u into the brain, and then render the brain.

For Task PLS, Design LV can help you to interpret which condition is distinguished by which LV:

LV = 1; % just an example. can be 2,3, ...

figure; bar(result.v(:,1));

If the bootstrap is applied, you can find which active area indicated by result.u is reliable. Let's use 95 percentile as threshold, we can find out the indices of the brain coordinate that are stable:

thresh = percentile(result.boot_result.compare_u(:,1), 95)

idx = find(abs(result.boot_result.compare_u(:,1)) > thresh);

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 PLSgui. The following appendix is a tool in PLScmd that allows people to plot the result of command-line PLS using Region of Interest (ROI) data.

10.3. 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 plots bootstrap results of ROI analyses 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:

A template image or a flood-filled image:

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.
Flood-filled image: An image that is created by this tool based on the template image and ROI seed location file (below).

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 program 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.

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:

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

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:

Start MATLAB add path for the plotroi tool.
Type plotroi to open the Information to plot ROI window.
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.
Load bootstrap ratio (compare) file.
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.
Select the LV you would like to see, and input the threshold for the selected LV.
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 Plot.
Before clicking Plot button, you can optionally input a title for the plotted ROI.
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.
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.
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:

http://www.rotman-baycrest.on.ca/pls/source/Plotroi_testdata.zip

11. Acknowledgments

Thanks to Prof. A. R. McIntosh, Dr. N. J. Lobaugh, Dr. W. Chau, Jimmy Shen, and many others who made contribution to this PLSgui project.

12. References

· McIntosh, A. R., F. L. Bookstein, J. V. Haxby, C. L. Grady (1996). Spatial pattern analysis of functional brain images using Partial Least Squares. Neuroimage 3: 143-157.

· Lobaugh, N. J., R. West, A. R. McIntosh (2001). Spatiotemporal analysis of experimental differences in event-related potential data with partial least squares. Psychophysiology 38: 517-530.

· McIntosh, A. R., W. K. Chau, A. B. Protzner (2004). Spatiotemporal analysis of event-related fMRI data using partial least squares. NeuroImage 23: 764–775.

· McIntosh, A. R., N. J. Lobaugh (2004). Partial least squares analysis of neuroimaging data: applications and advances. NeuroImage 23 Supplement 1: S250–263.

· McIntosh, A. R., N. J. Lobaugh, et al. (1998). Convergence of neural systems processing stimulus associations and coordinating motor responses. Cerebral Cortex 8: 648-659.

· Gargallo, R., C. A. Sotriffer, et al. (1999). Application of multivariate data analysis methods to comparative molecular field analysis (CoMFA) data: proton affinities and pKa prediction for nucleic acids components. J Comput Aided Mol Des 13(6): 611-23.

· Martin, Y. C., C. T. Lin, et al. (1995). PLS analysis of distance matrices to detect nonlinear relationships between biological potency and molecular properties. J Med Chem 38(16): 3009-15.

· Streissguth, A. P., F. L. Bookstein, et al. (1993). The enduring effects of prenatal alcohol exposure on child development: Birth through seven years, a partial least squares solution. Ann Arbor, Michigan, The University of Michigan Press.

· Wold, S., P. Geladi, et al. (1987). Multi-Way Principal Components and PLS Analysis. Journal of Chemometrics 1: 41-56.

· Edgington, E. S. (1980). Randomization tests. New York, Marcel Dekker.

· Good, P. (2000). Permutation tests: A practical guide to resampling methods for testing hypotheses. New York, Springer.

· Efron, B. and R. Tibshirani (1985). The Bootstrap Method for Assessing Statistical Accuracy. Toronto, University of Toronto.

· Efron, B. and R. J. Tibshirani (1993). An introduction to the bootstrap. New York, Chapman & Hall.

· Milan, L. and J. Whittaker (1995). Application of the parametric bootstrap to models that incorporation a singular value decomposition. Royal Statistical Society Journal, Series C: Applied Statistics 44(1): 31-49.