Session Profile

PLS session profile need to be created before running analysis. The file name of PLS session profile should look like this: prefix_MODULEsessiondata.mat. However, in PLS version 5.x or earlier, old file pair session.mat / datamat.mat were used. In order to make the version change seamless, a program session2sessiondata.m is provided, which can convert old file pair into a single sessiondata.mat file. For more information, please type: help session2sessiondata in MATLAB command window. For Structural MRI and ERP modules, sometimes there can be more datamat.mat files point to one session.mat file. In this case, simply copy the datamat.mat file to sessiondata.mat file, and keep the prefix of datamat.mat file. However, this does not apply to other modules.

In order to create session profile, raw data (scan images, ERP data etc.) must be saved in following ways before launching PLS Applications.

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

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

For Structural MRI module, all subjects with all conditions are kept in a single folder. The naming convention for raw data files in Structural module is critically important, which will be introduced in Creating Structural MRI sessiondata file section.

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

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

Creating PET sessiondata file

In PLS start window, click PET button and it 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.

Datamat Prefix is used to compose sessiondata file name. For example, if you put demo in this field, the sessiondata file will become demo_PETsessiondata.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 scan images for each subject should be kept in one folder, and all subjects for one analysis should be under a single folder. 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 PLS Applications.

Now, click Select Subjects button, and the 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:

1. All subject files consist 2 parts, subject initial part and condition name part. e.g. SubjInit1_CondName1
2. Across all subject directories, the condition name part should be the same for the same condition.
3. Within each subject directory, the subject initial part should be the same for all conditions within this subject.

Click Add button, and the 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:

1. Enter the length of the subject initials in the Number of Characters for subject initial box in previous window.
2. Select one of subjects that will be used in this datamat group (Note: Remember to only select 1 subject this time).
3. If you have Consistent Naming Across Subjects, you will notice that File names are the same across subjects check box is checked. Uncheck it to disable this feature.
4. 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.
5. If you have multiple subjects in this group, you can now select the rest of subjects by holding Shift or Ctrl key combination while selecting (Note: You cannot do so before this step).
6. Click Done button when you finish, and return 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.

Go back to PET session window, and click Create Datamat button to open Create PET Datamat window.

There are two ways to define brain region:

1. Use pre-defined brain region image file, which should have the same dimension and orientation as any PET scan images in the subjects. The intensity of the brain region image should be either 0 or 1 (binary image), where 1 stands for the brain region.
2. 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.

You can verify image orientation by clicking Check image orientation button. If you believe that the image orientation is wrong, you can click Re-orient button to make change.

Now, click Create button to generate PET sessiondata file.

Creating ERP sessiondata file

In PLS start window, click ERP button and it 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.

Datamat Prefix is used to compose file names for ERP sessiondata file and ERP data file. For example, if you put demo in this field, demo_ERPsessiondata.mat will be the ERP sessiondata file name and demo_ERPdata.mat will be the 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 above, all ERP raw data for each subject should be kept in one folder, and all subjects for one analysis should be under a single folder. Now, click Select Subjects button to select and edit subjects in subject folder. 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 that 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:

1. Put all electrode names on a piece of grid paper, and make sure that they are spatially located appropriately.
2. 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.
3. Use a ruler (or count the grid) to measure the x and y location from the origin.
4. 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   ]

5. Assume that your current folder is the one that you will save sessiondata & result files, then run:

save erp_loc_besa148 chan_loc chan_nam

Now you have your own electrode system in Edit Channel Order window if you select ERP/BESAThetaPhi system.

Obviously, here the ERP/BESAThetaPhi system now represents your own system instead of the real ERP/BESAThetaPhi system from PLS Applications. If you want to restore the real ERP/BESAThetaPhi system from PLS Applications, you can choose a different folder for different experiment, or simply remove erp_loc_basa148.mat file in this folder.

ERP module is very different from other modules, because of its small raw dataset. For this reason, we put all subjects with all conditions into one file, which we call it ERP data file. Then you can have several ERP sessiondata files point to one ERP data file, and each of those ERP sessiondata file is part (or all) of this ERP data. ERP data file is generated at the same time when you generate ERP sessiondata file.

Go back to ERP session window, and click Create Datamat button to open 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 the default 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 sessiondata 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 sessiondata file and ERP data file.

Modifying ERP sessiondata file and saving to a different file name

In ERP session window, click Modify Datamat button, and select an ERP sessiondata 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:

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

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

Creating E.R.fMRI sessiondata file

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

Figure 8

In the session window, Session Description is an optional field.

Datamat Prefix is used to compose sessiondata file name. For example, if you put demo in this field, the sessiondata file 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 clicking Edit Runs. It indicates how many runs of data will be used. Each run of data must be kept in a separate folder.

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

Figure 9

1. Number of Scans field must be specified first in this window.
2. 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.
3. 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.
4. 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.
5. 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 PLS applications fill the onset numbers for you. Click Save Onsets to a text file for this run will save the current filled numbers to a text file.
6. If Replicate trial information across run is selected (by default), the onset number will stay the same while you traverse from run to run.
7. 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.

Go back to E.R.fMRI session window, and 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 Temporal window size is 8 scans.

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 not checked for both E.R.fMRI and Blocked fMRI data. Don't select this check box unless you have good reason to do so.

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

Single reference scan will use the reference scan below 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 enter an absolute reference scan onset, instead of a relative reference scan onset.

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

Creating E.R.fMRI sessiondata file with user defined HRF

In PLS start window, click Blocked fMRI button and it 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 sessiondata file is for E.R.fMRI with user defined HRF; if you uncheck this box, your sessiondata file will become Blocked fMRI, which will be described below. Once you make the decision, it cannot be changed. If you really want to change, you will have to make a new sessiondata 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.

Go back to session window, click Create Datamat button to open the 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 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 not checked for both E.R.fMRI and Blocked fMRI data. Don't select this check box unless you have good reason to do so.

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 & HRF2. In 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. In 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 sessiondata file with user defined HRF.

Creating Blocked fMRI sessiondata file

Creating Blocked fMRI sessiondata file is almost the same as Creating E.R.fMRI sessiondata 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.

Creating Structural sessiondata file

In PLS start window, click Structural button and it 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.

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

Dataset Directory is where raw data of all subjects with all conditions are kept. The file name convention for dataset file here is criticlly important. All those file names have to be composed in three parts: subject part followed by condition part followed by dataset format part. For the same subject, different conditions should have the same subject part; for the same condition, different subjects should have the same condition part; the dataset format part should be either .nii or .img/hdr. For example, assuming that there are subjects "s1_" "s2_" "s3_" with conditions "wm" "gm" and format "nii", there must be at least six files in this folder: s1_wm.nii, s2_wm.nii, s3_wm.nii, s1_gm.nii, s2_gm.nii, s3_gm.nii.

Click _Input Condition_s 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 the Edit Subject Directory window will open (Figure 3). Now, click Add button, and the Subject Directory Detail window will open (Figure 16). You can select one or more subjects for this datamat group. By default, subject name is the dataset file name without condition filter part. If you feel the subject name too long, you can always change it in the Edit Subject Directory window.

Figure 16

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

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 to the default all selected.

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

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

Modifying Structural sessiondata file and saving to a different name

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

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

Click Modify button to save the modified sessiondata file.