FAQ.txt

	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.