Frequently Asked Question for PLS Applications
==============================================
Q: Why the figures in UserGuide.htm cannot be displayed?
A: Those figures are stored in our website, you need to connect
to internet in order to view them. If you still have problem
to view the figures, please check the webpage address of the
User Guide for PLS Applications. Make sure it is:
http://pls.rotman-baycrest.on.ca/UserGuide.htm
Q: Besides GUI interface, how can I get meaningful information
directly from PLS result file (i.e. *result.mat)?
A: In "result" structure variable, there is a field called
"field_descrip", which is a mapping list between all the
field names in result variable and their meaningful names.
Q: Can I enter decimal number in "Onsets" field for MRI study?
A: Yes, you can. However, since the smallest unit is a scan (i.e.
1 TR), the PLS application will round your decimal number to
integer.
If you selected "Use HRF instead of Block length", we adopted
some feature from SPM. Instead of only using 1 time bin, SPM
increases the Microtime resolution 16 times. This may bring
some benefit if you input decimal onset time directly, though
eventually the length of convolved onsets is still the number
of scans (i.e. one scan is still the smallest unit). If you
input decimal onset time directly, please make sure that your
slices must be in sequential order rather than interleaved
order. Also, please make sure that your slices must be in
ascending order (i.e. 1st slice is at bottom) instead of
descending order or rounding order. Otherwise, you must enter
integer for the onset time.
For all other fMRI PLS, since they are either based on
temporal window or block length, there is no chance to take
decimal onset time. If you do input decimal onsets, they will
be rounded to the bottom slice using "round" function (before
Feb 24, 2011, they were rounded using "floor" function).
Q: How many LVs do I have?
A: The number of LVs that generated by our PLS applications is
determined by which option that you choose to run PLS:
For Mean-Centering PLS: nLVs = nConditions x nGroups;
For Non-Rotated Task PLS: nLVs = nContrasts;
For Regular Behavior PLS: nLVs = nConditions x nGroups
x nBehaviorMeasure;
For Multiblock PLS: nLVs = nConditions x nGroups + nConditions
x nGroups x nBehaviorMeasure;
For Non-Rotated Behavior PLS: nLVs = nContrasts;
For Non-Rotated Multiblock PLS: nLVs = nContrasts;
There are also several restrictions:
1. Since nConditions only provide nConditions-1 degrees of
freedom, the maximum number of contrasts is limited by
nConditions;
2. In order to run Behavior PLS, you need to have at least 3
subjects;
3. In order to run Mean-Centering PLS, you need to have at
least 2 conditions. However, if you have only 1 condition
and you have more than 1 groups, our PLS will reconstruct
datamat so that it will become single group with multiple
conditions.
Q: Which side is the left side of my image?
A: If your raw image is in NIfTI format, PLS will interpret the
header and display it in RAS orientation. i.e. from 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.
If your raw image is in ANALYZE format, PLS will display
whatever orientation in raw image, since there is no affine
matrix in its header. However, you can change orientation
when you create the datamat.
Q: Can I use ANALYZE image with different orientation?
A: Yes. A new feature has been added to the version of Oct. 29
in 2004. This allows people to use ANALYZE images in any
orientation for PET, Structural, 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 Cardinal Plane 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. After done, the PLS will display the image
in RAS orientation. i.e. from Left to Right on X axes, from
posterior to Anterior on Y axes, and from Inferior to
Superior on Z axes.
Q: Can I use a 4D NIfTI or ANALYZE image?
A: Yes. For E.R.fMRI or Blocked fMRI modules, you can use a 4D
image directly. For other modules, all you have to do is to
run a small program called "expand_nii_scan.m" under command
promot, and expand all the 3D scans in that 4D image into a
directory.
Q: Does PLS support ANT average binary data?
A: Yes. The "load_ant.m" program in PLS is based on openlib
library "cntopenlib.zip" and other information in "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.
My "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 PLS. 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 channel names with their corresponding
x and y locations. Because PLS will normalize the locations to
Xmin/Xmax and Ymin/Ymax, you don't need to worry about the
exact locations.
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 also serves a good selection.
3. Third step: Use a ruler (or count the grid) to measure the
x and y locations from the origin.
4. Forth step: Pick any of the 4 PLS electrode systems for
your system. In PLS, each system is determined by a
"erp_loc*.mat" MATLAB file. We have:
erp_loc_besa148.mat (default)
erp_loc_egi128.mat
erp_loc_egi256.mat
erp_loc_ctf150.mat
Since "erp_loc_besa148.mat" is the default system for
"Edit Channel Order" window, it will be convenient for
you if you also pick this one.
The whole idea is to write one of the four files above in your
own PLS working directory. So PLS will pick the one in your own
directory (the same directory for sessiondata file and result
file), rather than the PLS applications directory.
All four electrode system files in PLS contain two variables:
1. chan_nam (char array) - the number of rows is the number of
channels; the number of columns is the longest length
of the electrode names.
2. chan_loc (double array) - the number of rows is the number
of channels; column one is for x values, and column
two is for y values.
For 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]
save erp_loc_besa148 chan_loc chan_nam
Now you will use your own electrode system in "Edit Channel
Order" window if you select "ERP/BESAThetaPhi" system.
Q: I wrote a batch file to create fMRI datamat. I have five
conditions and two runs. Since I set "across_run" keyword to
"0" (merging data within each run), I will have ten 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 five conditions after five "cond_name"
keywords. This is because PLS applications will expand your 5
conditions in your 2 runs to something like Run1Cond1, ...,
Run2Cond4, Run2Cond5, etc.
Q: What should be the content of 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 content. 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 locations in voxel to
locations in 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 sessiondata.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:
I = []; xyz = xyzmm2xyz(xyzmm, result_file);
for i = 1:size(xyz, 1)
I = [I; 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:
data = (data - ref_data) * 100 ./ ref_data
This way, activity for each event is expressed as a percentage
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: I have completed a group analysis with 7 subjects under 3
conditions (positive, negtive and neutral) using Non-Rotated
Task PLS. 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 high negative) voxels in the
Bootstrap Ratio view. "Brain LV" gives you a "activation map",
so it is the one to support your experiment result. The
positive (negative) values in "Brain LV" 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 in "Merge data" under session
window, choose "Across All Runs" to create a datamat. Please
ignore the command line message saying "Scans -01 not included
due to out of bound". You cannot 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 cannot 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) an
insignificant value to make it work.
Q: Is there any restriction on file name?
A: Yes, but not many. There are 2 kinds of major files that will
be used in PLS applications. They are sessiondata file, and
result file.
The 2 major files must be in the forms of:
*_MODULEsessiondata.mat
*_MODULEresult.mat
You can replace MODULE with any of PET, ERP, fMRI, BfMRI, or
STRUCT depending which PLS method are you working on, and the
dialogbox will always prompt you with the correct MODULE.
You cannot 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 PLS applications. 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. But I checked and the datamat
files are there in my datamat directory.
A: In the early version of PLS applications, we placed the datamat
files location in the 'pls_data_path' variable. However, this
also caused troubles when people tried to copy those datamat
files from directory to directory, and even from one computer
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.
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.
Each raw data inside the subject directory stand for one
conditions in this subject. The name of these files can be
arbitrary; however, if you give "consistent naming across
subjects", it will be convenience for you to match those
conditions.
Here is what the "consistent naming across subjects" means:
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.
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 default -1)
2. Click Add or Edit button in the same window (Edit Subject
Directory window), and a window called Subject Directory
Detail will open.
3. Select one of subjects that will be used in this datamat
group (Note: Remember to 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 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).
7. Click Done button when you finish, and 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
can 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 show
such an error message. If you definitely need such a mapping,
then the "consistent naming across subjects" rule cannot 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), checkbox
"File names are the same across subjects" 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 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 "ERP_data1", and the second
data file "erp_Data2".
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: After deselect the conditions, why the behavior data I loaded
before running analysis get lost?
A: This is because rows of behavior data are determined by the
conditions you selected. So, you need to load behavior data
again 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: I literarily counted those active voxels, why are they not
listed in PLS cluster report? The two clusters in the cluster
report are within the same cluster, why PLS 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
techniques 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 has 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 PLS 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 clusters. In that case, all those
clusters have to be combined together. However, if the new
cluster cannot 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 PLS may separate active
voxels in the same cluster into different clusters.
