Frequently Asked Question for PLS Program
=========================================
Q: Which side is the left side of my image?
A: If your image data is in NIfTI format, PLSgui always load, save,
and display your image in RAS orientation. i.e. Left to Right on
X axes, from posterior to Anterior on Y axes, and from Inferior to
Superior on Z axes. Therefore, left side is the left side of your
image.
However, if your image data is in ANALYZE format, please refer to
the answer below to manually adjust the orientation of your image.
Q: Can I use Analyze image with different orientation?
A: Yes, a new feature has been added to the version of Octobor 29,2004.
This allows people to use Analyze images in any orientation for PET,
E.R.fMRI and Blocked fMRI. In "Create Datamat" window, a new button
named "Check image orientation" is added beside the "Create" button.
Once you click this button, the 3-View of one of the subject images
will be displayed in the "Change Image Orientation" window, and you
can re-orient it by click the "Re-orient" button. Once you click the
"Re-orient" button, it will ask you to input the orientation of the
CURRENT DISPLAYED image. If you did not get the correct orientation,
you can do as many times as you want to make it standard Analyze
orientation, i.e. from Left to Right in X orientation, from Back to
Front in Y, and from Bottom to Top in Z. If you closed the "Change
Image Orientation" window, you can re-open it by click the "Check
image orientation" button in "Create Datamat" window again.
Q: Does PLSgui support ANT average binary data?
A: Yes. The "load_ant.m" program in PLSgui is based on openlib
library "cntopenlib.zip" and additional information "avr.txt"
file that are released by ANT technical support.
Since January 2004, ANT's average data file has been changed,
and the history section is included in its header. This info
is not included in the "cntopenlib.zip"; however, it is in the
"avr.txt" file released by ANT's support people.
Some people used "avr2asc" provided by ANT's EEProbe_3.3.120
to convert ANT's average data to plain text file. However, the
disadvantage is that the "avr2asc" only supports new version
of ANT's average data on Linux and Mac platforms, and does not
work under MATLAB.
Other programs relied on their "cntopenlib.zip" (e.g. Robert
Oostenveld's "read_eep_avr" that is used by EEGLAB) can only
support old version, and they are compiled in mex or dll file.
You must first use "avrstrip" in EEProbe_3.3.120 to convert
your new version of ANT's average data to old version before
you can use "read_eep_avr" to load them.
The "load_ant.m" is the only explicit .m program so far (April,
2007) that supports both old & new versions of ANT's average
data file on any platform.
Q: In my MEG data, the number of channels and their corresponding
names do not match up with any of the pre-specified system. How
can I read in my data when channel configuration and names do
not match?
A: Up to this version (5.0704231) We only have 4 scalp electrode
location systems in PLSgui. They are the ones that we are using
most frequently. There is a way to add any system by yourself,
as long as you know the electrode names with their corresponding
x and y locations. Since PLSgui will normalize your x and y
location to Xmin/Xmax and Ymin/Ymax, you don't need to worry
about the exact locations, and the relative ones will work.
Here is the details of how to add a Standard 10-20 EEG System
with 19 cap electrodes:
1. First step: Put all electrode names on a piece of grid paper,
and make sure that they are spatially located appropriately.
2. Second step: 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. Third step: Use a ruler (or count the grid) to measure the
x and y location from the origin.
4. Forth step: Pick any of the 4 PLSgui electrode systems for
your system. In PLSgui, each system is determined by a
"erp_loc*.mat" MATLAB file. So we have:
"erp_loc_besa148.mat", "erp_loc_egi128.mat",
"erp_loc_egi256.mat", and "erp_loc_ctf150.mat". The default
system for "Edit Channel Order" window is:
"erp_loc_besa148.mat". So, it will be convenient for you if
you pick this one.
The whole idea to use your own system is to create an electrode
systems MATLAB file with the same file name as the one used by
PLSgui. Let's assume you picked "erp_loc_besa148.mat", once you
save your own "erp_loc_besa148.mat" in the same folder as the
one you will save session/datamat/result file, PLSgui will load
your own "erp_loc_besa148.mat", instead of the one from PLSgui
program folder.
All 4 PLSgui electrode system MATLAB file in PLSgui contain two
variables, one is char array "chan_nam", the number of rows is
the number of channels and the number of columns is the longest
length of the electrode names; the other one is double array
"chan_loc", the number of rows is the number of channels and
it only has two columns. Column 1 is for x values, and column 2
is for y values. Now continue with this example:
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:
%
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.
Q: I am not using MATLAB in MS Windows platform now. When I click
"How to use this window?" under help menu, I only get "To learn
how to configure your Web browser type 'help docopt'" message in
MATLAB command window. When I did so using MATLAB in MS Windows
platform, I can see that the help is nicely opened in my default
web browser. Does it mean that this menu can only be used in
MATLAB in MS Windows?
A: This menu should work on both Windows and Unix (Linux). I have
not tested it on other OS.
However, you could still encounter error (the message in your
question is automatically displayed by MATLAB) because of the
following reasons:
1. You are using MATLAB version 5. It does not have a MATLAB
desktop, and it uses the current terminal for commands.
2. You specified -nodesktop or -nojvm when you launch MATLAB.
3. You do not have any web browser in your system, or you did
not specified properly in "docopt.m" file. In latter case,
please type 'help docopt'.
In any case, in fact, I recommand PLS user to manually open your
favorate web browser, and view our PLSgui User's Guide from PLS
web site:
http://www.rotman-baycrest.on.ca/pls/UserGuide.htm
Q: Why the figures in UserGuide.htm can not be displayed?
A: Because those figures took hundreds of kilobytes of the space, I
have to leave them in our website. As long as your computer have
internet access, you will be able to see them properly, even if
you browse "UserGuide.htm" that is on your local computer.
Q: I wrote a batch file to create fMRI datamat. I have 5 conditions
and 2 runs. Since I set "across_run" keyword to "0" (merging data
within each run), I will have 10 conditions. I listed all 10 after
10 "cond_name" keywords. When I run the batch, I got error message
saying "Index exceeds matrix dimensions".
A: You can only list your 5 conditions after 5 "cond_name" keywords.
This is because the program will expand your 5 conditions in your
2 runs to something like Run1Cond1, Run1Cond2, Run2Cond1, etc.
Q: I preprocessed my data in FSL, where left is R and right is L. I
then entered the normalised, slicetime- and motioncorrected data
into a PLS analysis. When we now look at the results, where is
left and right? As in FSL?
A: Let's use command: nii = load_nii('filename.nii'), where
"filename.nii" is the one from FSL:
1. If you find nii.filetype is 0, it means that the image
orientation is as is in the data.
2. If filetype is not 0, and there is no "rot_orient" &
"flip_orient" field under "nii.hdr.hist", it means that
your data is already in RAS, and my NIFTI package did not
convert your data.
3. If file type is not 0, and there is "nii.hdr.hist.rot_orient"
or "nii.hdr.hist.flip_orient", it means that your data has
been converted to RAS (Left is L) by NIFTI package.
Q: What should the contents of the input file for "multiple voxel
extraction"? I created a text file with 1 XYZ coordinate per row.
However, I keep getting an error message.
A: That's the correct contents. However, please make sure that the
XYZ coordinates should be in unit of millimeter. (Note, we did
use absolute voxel location before 15-SEP-2006. You can use
script "xyz2xyzmm.m" to easily convert absolute voxel location
to voxel location with unit of millimeter.)
Q: When I use the multiple voxel extraction, does it output the
baseline-adjusted values or the raw image values?
A: It outputs the baseline-adjusted value (from *datamat.mat), and
there is no raw image values kept. If you need raw image values,
you have to load images by yourself, and extract only the voxels
indexed by the XYZmm file you provided.
Q: I would like to get intensity values at particular coordinates
from the raw image. How do I load image and extract the voxel
intensity from XYZmm file?
A: Let's say your raw image is:
filename = 'SCAN.img';
or filename = 'SCAN.nii';
and you would like to get the intensity values at particular
coordinates from it.
First, you need to load the image by yourself:
A = load_nii(filename);
Then, display the image:
view_nii(A);
Since you have already prepared XYZ(mm) in voxel file, you
need to switch the selection of "Axes Unit" from "Voxel" to
"Millimeter", and then enter each XYZmm value in "[X Y Z]
at crosshair" field and click TAB key.
The value displayed in "Value at crosshair" is the intensity
value at the particular coordinate you entered.
If you have many coordinates, you can use the simple script
below to automatically extract intensity values list from
locations list in your XYZmm file:
intensity=[]; xyz = xyzmm2xyz(xyzmm, result_file);
for i=1:size(xyz,1)
intensity=[intensity;A.img(xyz(i,1),xyz(i,2),xyz(i,3)];
end
Q: In E.R.fMRI and Blocked fMRI datamat create window, what does
the "Normalize data with ref.scans" check box mean?
A: This check box is checked by default to remove the low frequency
noises and scale the data. The formula for this check box is very
simple:
dataset = (dataset - ref_dataset) * 100 ./ ref_dataset
In this way, activity for each event is expressed as a %change
from the reference scan (i.e., baseline) similar to what is done
for ERP, where activity is expressed as a change from prestimulus
baseline.
Please keep this check box checked unless you have a good reason
not to do so.
Q: Also in E.R.fMRI and Blocked fMRI datamat create window, when the
"Single Subject Analysis" check box was checked, the red words
"Number of onset must be same" were presented in the bottom of
this window, however,when this check box was not checked, session
session file could be created successfully. Why?
A: For single subject analysis, we actually treat each onset as
a "subject" (in the sense of our "subject-in-condition-in-group"
format). This is why we need you to keep onset number same,
because the number of "subject" should be the same for each
"condition" in each group.
If you uncheck the single subject analysis, all the onsets for
each condition will be averaged together, so there is no need to
keep onset number same.
Q: I have three conditions (positive, negative and neutral) and I
want to compare the effect of positive vs neutral, if the
"Mean-Centering PLS" is cheked, how do I "deselect" conditions
in the window of "PLS Analysis"?
A: Click "Deselect Conditions" under "Deselect" menu, and deselect
the "nagative" condition.
Q: What does the "Non-Rotated Task PLS" check box in "PLS Analysis"
window means?
A: In "Non-Rotated Task PLS", we directly used crossblock between
the contrast data and the task mean of your fMRI data as brainlv,
and directly used sum of squre of the crossblock for singular
value. There is no PCA computation involved, and there is no need
to do procrustean rotation for the result. This is why we call it
"Non-Rotated Task PLS".
Q: If the "Non-Rotated Task PLS" check box is checked, how do I
design the contrast?
A: Click "Contrast" menu in PLS analysis window. Click "Using Helmert
Matrix" under the "File" menu of the contrast window. The freedom
of contrast is number of conditions minus 1. For example, if you
have 3 conditions, you can have 2 contrast. You can either take
the Helmert Matrix value in the text box, or re-enter your own
contrast value (e.g. [-1 1 2], [1 -2 3] etc.). At the end, you
have to go to "File" menu to save your contrast data into a file,
and this file name will be entered into the "Contrast Data File"
in the PLS analysis window (you can only enter file name under
"Non-Rotated Task PLS" option.
Q: I have completed a group analysis with seven subjects under three
conditions(positive, negtive and neutral) using Helmert contrast,
when showing the result, how could I find the the values of latent
vectors for design contrast?
A: Click "Design Scores and LVs Plot" in the "Windows" menu of the
result display window. The Design Scores for each latent variable
reflect the impact of your contrast data.
Q: In my result the "Brain LV" view is very different from the
"Bootstrap Ratio" view with default threshold, and which view do
I prefer to support my experiment result?
A: The "Bootstrap Ratio" view gives you a "stability map", so you can
focus on the high positve (or negative) voxels in the "Bootstrap
Ratio" view. However, "Brain LV" view is the one to support your
experiment result. The positive (negative) value should be
consistent with the one in Design Scores plot.
Q: I have more than one runs in my MRI study. However, for some
runs, I do not have all the conditions. How should I fill out
the onset field?
A: If you want to exclude certain conditions for certain runs,
you can simply put a -1 for the onset field, (and put a 1 for
the length of Blocked fMRI). Then choose "Merge data of each
condition: across all runs" to create a datamat. Please ignore
the command line message saying "Scans -01 not included due
to out of bound". You can not choose "Within each run only",
since you do not have all the conditions filled for every
runs. In additon, for each condition, you must have at least
one valid onset (not -1) in one of your runs.
Q: Why the results I obtained using Matlab 7 can not be loaded
under earlier version of Matlabs?
A: In order to load results generated using Matlab 7 on earlier
versions of Matlab, a special Matlab 7 switch must be included
during the saving process. Since such a switch is not coded in
the package, a small program called 'matlab7to5.m' is included
to covert the .mat files generated from Matlab 7 to be loaded
on earlier versions of Matlab that are above Matlab 5.
Q: I got "divide by zero" error when I tried to run Behavior PLS
analysis, while there is no error when I ran task PLS.
A: There are two reasons that could bring you into this trouble:
1. You must have at least 3 subjects to do the behavior PLS.
2. Values should not be all the same for behavior data. Even
if they are really all the same, you must add (or minus) a
slight difference (e.g. 1/1000) to make it work.
Q: Is there any restriction on file name?
A: Yes, but not many. There are 3 kinds of major files that will
be used in this program. They are session file, datamat file,
and result file.
The 3 major files must be in the forms of:
*_MODULEsession.mat
*_MODULEdatamat.mat
*_MODULEresult.mat
You can replace MODULE with any of PET, ERP, fMRI, or BfMRI,
depending what PLS are you working on, and the dialogbox will
always prompt you with the correct MODULE.
You can not insert your own string into the above forms and
break it. However, you can always use your own string before
"_MODULE", which is called "prefix" in the program. I do not
recommend you to use any blank space or symbol characters
like "+ - * / % ^ $ ' ..." etc. inside the string.
In addition, you should not rename the filename manually by
yourself, since this will break the filename linkage stored
inside the above major files.
Q: When I opened the result file, it crashed and told me that the
datamat file was unable to open. (No, the datamat file was not
in the current directory.)
A: In the early version of the PLSgui program, we used the stored
'pls_data_path' variable to locate the files. However, this also
caused trouble when people want to copy those datamat files from
directory to directory, and even from one machine to the other.
So, we decided to use the "current directory" rather than the
stored 'pls_data_path' variable for "Run PLS" window and "PLS
result" window. If you are not starting the program from the
"current directory" where those datamat files sit, you can
always change to "current directory" in the very first window
by clicking "Change Current Working Directory" under "Tools"
menu.
Q: When I add or edit subject directory for ERP and PET, I saw an
edit box called "Number of character for subject initial". What
should I enter?
A: For ERP and PET data, each subject has its own directory. The data
files inside the subject directory stand for different conditions
for this subject. The name of these files can be arbitrary; however,
if you give "consistent naming across subjects", it will bring you
convenience to match the conditions.
Here is what the "consistent naming across subjects" means:
1. All subject files consist two portions, subject initial portion
and condition name portion. e.g. SubjInit1_CondName1;
2. Across all subject directories, the condition name portion
should be the same for the same condition;
3. Within each subject directory, the subject initial portion
should be the same for all conditions of this subject;
Here is how to make this feature work for you:
1. Enter the length of the subject initials in the "Number of
Characters for subject initial" box. You can disable this
feature by leaving this value as -1.
2. Click Add or Edit button in the same window (Edit Subject
Directory window), and a new window called Subject Directory
Detail will open.
3. Select one of subjects that will be used in this datamat
group (Note: Remember that only select 1 subject this time).
4. 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.
5. 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.
6. 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 so
before this step).
7. Click Done button when you finish, and you return to "Session
Information" window.
Q: I received a "Subject file name convention is not consistent"
message when I try to edit a subject. However, all my subject
file name convention are consistent. Is this a bug?
A: No, it is not a bug. When you edit a subject with "File name
are the same across subjects" checkbox selected, the program
expects that you are trying to use a different subject. You
should manually do the mapping between subject files and input
conditions by yourself. If the mapping you selected does not
follow the other subjects you selected, the program will display
such an error message. If you definitely need such a mapping,
then the "consistent naming across subjects" rule can not be
kept, and you will have to uncheck the "File name are the same
across subjects" checkbox.
Q: All my subject files have consistent naming convention, and I
also input the correct length in the "Number of Characters for
subject initial" box. Why the "File names are the same across
subjects" checkbox is grayed?
A: Please check the following 2 possibilities:
1. All files under any subject directory should follow the
"consistent naming across subjects" rule. If one of them
does not follow this rule (e.g. WS_FTP.LOG), the "File names
are the same across subjects" checkbox will be grayed.
2. Don't let external program affects your subject initial. For
example, there is a subject file with subject initial "S1"
with length of 2 characters. When you normalize this file,
it may become nS1 with length of 3 characters. You will have
to rename the file name if this happened.
Q: Does the length of the data file name matter?
A: No. It can be any length. However, please make sure that subject
initial portion should be the same length if you would like to
use the "consistent naming across subjects" feature.
Q: Does the letter case of the data file name matter?
A: No. It is particularly designed for case insensitive. So you can call
the first data file name "JSdata1", and the second "jsData2".
Q: What can this PLS Program do?
A: PLS indicates Partial Least Squares (PLS) analysis method.
It is based on the assumption that the focus of analysis
is on which aspects of the signal in one matrix are related
directly to signals in another matrix.
This PLS program is applied to neuroimaging data, such as
PET, ERP, Event Related fMRI and Blocked fMRI. It has been
used to identify the task-dependent changes in activity,
changes in the relations between brain and behaviour, and to
examine functional connectivity of one or more brain regions.
The similarities and differences in brain-behavior relations
can be identified from the resultant patterns.
Q: What data should I prepare for analysis?
A: The data can be obtained from PET, ERP, or fMRI scan images.
For PET and ERP data, you put different condition of data for
each subject into its corresponding directory. For fMRI data,
you put each run of data into its corresponding directory.
Q: I made some changes, but it disappeared. Why?
A: Any changes you made on the edit box need to be recorded. This
can be done by clicking "Enter" key on your keyboard, or simply
click anywhere else on the window to let the focus switch off
from this edit box. If you did not let the focus switch off from
this edit box, the change will not be recorded.
Q: What should I enter for "Edit Behavior Data"?
A: For PET and ERP data, the number of rows for behavior data should be
the number of conditions times the number of subjects, in the order
of subjects in conditions:
cond1/subj1
cond1/subj2
...
cond2/subj1
cond2/subj2
...
For fMRI data, the number of rows for behavior data should be either
just the number of conditions, or the number of conditions times the
number of runs, depending on whether you choose of "across run" or
"within run" when you create datamat. The order should be either all
conditions, or runs in conditions:
for across run:
cond1
cond2
...
for within run:
Run1Cond1
Run1Cond2
...
Run2cond1
Run2Cond2
...
The column of the behavior data should correspond to the different
sets of the behavior measures.
Q: When I exported data for behav analysis for PET module, I saw the
exported file name looks like "?_PET_grp?_behavdata.txt". For the
both E.R.fMRI and Blocked fMRI modules, however, it looks like
"_fMRI_grp?_subj?_behavdata.txt". Why the PET module does not
include the subject information?
A: For PET module, each datamat (and session file) represents a group
that already contains subjects. However, for fMRI, each datamat (and
session file) represents a subject. So, for fMRI, we need behavior
measure of each subject in the group in order to add it into datamat
(from session profile). For PET, we need behavior measure of each
group.
Q: Can I rename the session / datamat / result files manually? Why the
corresponded session file also changed its name, after I save as
fMRI datamat into another file name?
A: We do not recommend you to change name manually. For fMRI, there is
some internal processing between session / datamat files. That's why
the session file name will be changed after you saved datamat file
into another name.
Q: After deselect the conditions, why the behavior data I loaded before
running analysis get lost (or still use the one from datamat)?
A: Because the rows of behavior data is determined by the conditions you
selected. So, you need to load behavior data after you deselect the
conditions.
Q: When I generate fMRI datamat, I got something like this: Scans 147 for
the condition 3 of run1 are not included due to out of bound. Do you
have any idea what this means?
A: When you enter onset data, make sure they are in the range.
In most case, you encounter this problem because the onset
data you input exceeds the maximum range. The minmum value
is started from 0. However, The maximum value you can enter is:
Number_of_Scans - Temporal_Window_Size_if_fMRI - 1. E.g.: If you
have 180 files, and window size is 8, the maximum value in onset
data is 171.
Q: What is the lag number? Is there anywhere I can enter lag values?
A: In E.R.fMRI, lag number is the index of the temporal window, and it
starts from 0. You decide the temporal window size in "Generate ST
Datamat" window. The unit of temporal window size is scan, and its
default value is 8. In "LagXYZ" field of result window, you can
enter lag value, as well as XYZ coordinates in voxel.
Q: In our lab we use AFNI in the processing of fMRI data but I would
like to use the PLS program to analyse an event-related dataset
and further progress to conducting a functional connectivity
analysis. My problem is that the PLSgui seems to need separate
image files for every time volume (a separate image file for every
'scan' in a run), however, using AFNI, the raw 2D timeseries is
transformed into a 3D dataset, upon which the motion correction,
edge-detection and spatial normalisation processing steps are
carried out. Can the PLSgui read in this entire timeseries or
must the time volumes be somehow extracted from this file?
A: For MRI module, PLSgui can read the entire timeseries volumes. For
PET / Structural module, PLSgui can only read 1 volume by 1 volume.
In that case, you can always use "expand_nii_scan.m" in PLSgui
program to expand 1 entire timeseries volumes into 1 folder. In
addition, the best way to convert AFNI BRIKs into NIfTI files is
to use 3dAFNItoNIFTI. The best way to convert NIfTI files into AFNI
BRIKs is to use 3dcopy.
Q: I literarily counted those active voxels, why are they not listed
in PLSgui cluster report? The two clusters in the cluster report
are within the same cluster, why PLSgui separate them into two
different clusters? The result of cluster report on one computer
is totally different from the cluster report from the other one,
but I have the same result file, and the same threshold. Why do I
get the different results?
A: In order to answer the questions, I have to describe the technique
used to generate cluster report. The author of the cluster report
program uses a 3D 6-connected operator to recursively flood and
fill the active voxels of the cluster. The MATLAB on each computer
can have different recursion limit, that's the reason you may expect
different cluster report on different computers. Also because of
the recursion limit, the flood and fill process may not complete,
i.e. there are still active voxels in the cluster that have not
been identified. That is the reason that some active voxels may
not be listed in PLSgui cluster report. When cluster report program
start the flood and fill from a different location, the new cluster
may join one or more of the old cluster(s). In that case, all those
clusters have to be combined together. However, if the new cluster
can not join the old cluster(s), it will look like an individual
cluster, although it could be part of the other cluster. That is
the reason that PLSgui may separate active voxels in the same
cluster into two or more different clusters.
