====== Using FSL ======

For reference, the FSL-FEAT analysis guide is available at [[http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FEAT/UserGuide]]

There are FIVE basic parts of FSL described in this page.
  - Converting data files to format used by FEAT (Section I).
  - Setting up a model and running first level analysis with FEAT (Section II).
  - Writing batch and template scripts (Section III).
  - Running MELODIC for Independent Components Analysis (Section IV).
  - Running second level FEAT (Section V).
  - Troubleshooting & Problems (VI).

Parts I-II can be done individually or by making a batch script. Instructions to batch file conversions are [[biac:fsl:guide#Batching|here]]. Instructions for batching FEAT analysis are in [[biac:fsl:guide#III. Writing a batch script for FSL|III. Writing a batch script for FSL]]. 

===== Logging in to the Cluster =====
[[biac:cluster:access|Connecting]]


===== Accessing your experiments =====
[[:biac:cluster:interactive#accessing_experiments|Accessing experiments]]

====== I.Preparing for FSL ======
  ===== Overview =====
  * You will need a number of things to run a FEAT analysis, and this section describes how to create these things. 
What You Need:
  - A tab delimited **3 column format text files** of your behavioral data. First column is event onset, second event duration, 3rd is typically 1 unless you have reasons to differentially weight some events.  For each condition of each run of each subject, you will need a separate 3 column format .txt document. So if you have 8 conditions, you will have 8 separate behavioral .txt files for each run of each subject!!! **NOTE** If you have a block design you do not need these :)
  - **nifti.gz formatted anat and func** files in LAS orientation
  - An **anat_brain.nii.gz**, which you get by running BET on your nifti anats 
  - A **template.fsf**, which is a really long Unix script that describes your full analysis model
  - A **batchFSL** script, again a Unix script, but this one defines input and output directories, etc., so that you can analyze all the runs of one subject with one script.

===== Instructions =====
  * Unordered List Item Change to the functional directory:
<code>
 cd `findexp Poker.01`
 cd Data/Func/30933/run01
 # findexp will print the location of your experiment, 
 # but cd `findexp EXP.01` will execute the cd (change directory) command on the results
 </code>
      
  * Convert the functional data to NIFTI format in LAS orientation:
<code>
  bxhreorient --orientation=LAS run004_01.bxh run01
  #the default output type of most bxh-tools is .nii.gz
</code>
  * This will create run01.nii.gz and run01.bxh

  * Change to the anatomical directory
<code>
  cd ../../Anat/20050929_30933/series002
  # ../ means go back 1 directory, so ../../ is going up 2 directories to Data
</code>

  * Convert the anatomical data to NIFTI format in LAS:
<code>
  bxhreorient --orientation=LAS series002.bxh anat
</code>

  * This will create the same sorts of files as for the functionals above ( anat.nii.gz anat.bxh ).
  * Run BET on your anatomicals. On the main FSL GUI, click **BET Brain Extraction**. 
  * Then, select the anatomical you just created as your input image. 
  * For the output image, copy and paste the text in the **Input image** text box into the **Output image** text box, and append a **b** at the end.
  *  __Generate image with non-brain matter removed__ should be checked. __Generate image... overlaid on original__ should be unchecked. 
  * For this, you do not need any of the advanced options.
  * Click **OK**. It will quickly (within a minute) generate a file like "anat_brain.nii.gz".
  * Type **fsl &** (case-sensitive) at the prompt. A little GUI will pop up. The ampersand runs fsl in the background, allowing you to do useful things like check the status of your processes.
  * Click on **FEAT FMRI Analysis**. A different GUI will pop up after a few seconds. You can close any excess GUIs that arise.





====== II.Setting-up First-level Analyses with FEAT ======
Note that if your runs have any differences in their design (e.g., differences in event timing), then you will need to conduct each first-level (i.e., run) analysis independently. This means that you will need to run FEAT six times if you have six distinct runs. You can automate some of the data input from this section by saving the FSF file after setting up the first run and then modifying it for the designs of the second runs.

====== Preprocessing ======
  - In the GUI, go to the **Data** tab. Ensure that **First-level analysis** and **Full analysis** are selected in the drop down lists at top.
For __Number of analyses__, indicate **1**, unless you have multiple runs with exactly the same timing. Click **Select 4D data**. Select the NIFTI *.hdr file you created earlier. The **Total volumes** box should update to reflect your header information. If you need to delete some volumes (e.g., if you did not have DISDAQs), then indicate that in the box at bottom right. You should also indicate the **correct TR (e.g., 1.5)**.
  - In the GUI, go to the **Pre-stats** tab. __Motion correction__ should read **MCFLIRT**. __B0 unwarping__ should be left unchecked. __Slice timing correction__ should be **Interleaved** in almost every case. __BET brain extraction__ should be checked. __Spatial smoothing__ should be **5mm**. __Intensity normalization__ should be unchecked.__Temporal filtering__ should be Highpass. __MELODIC ICA__ should be unchecked in most cases.
  - In the GUI, go to the **Stats** tab. __Use FILM prewhitening__ should be checked. For __Add motion parameters to model__ you should select **No**. 
  - In the GUI, go to the **Registration** tab. __Initial structural image__ should be unchecked. __Main structural image__ should be checked. Select the anatb.hdr file (i.e., the BET brain-extracted anatomical) you created earlier. 

===== Design =====
Entering your design is the most complex aspect of FSL (and every other fMRI analysis program). For most of what we do, you should go to the **Stats** page, and then click **Full Model setup**. This will pop up yet another GUI, the General Linear Model.

  * Indicate how many different explanatory variables (EVs) you have in the box at top. This is typically the number of conditions, potentially including multiple parts of each trial separately (e.g., decision phase followed by outcome phase). 
  * Label your first EV in the box **EV name**. Then, repeat the next step for each EV.
  * For __basic shape__, in most cases, you will choose **Custom (3 column format)**. Information about that format can be found [[biac:fslguide_3column|here]]. You will need to select one file for each condition/event type. For __convolution__, you can use **Double-Gamma HRF**, with __Phase__ set to 0. __Orthogonalise__ will typically be **checked**. __Add temporal derivative__ will typically be **unchecked**. __Apply temporal filtering__ should be **checked**.
  * Once you have entered all of your EVs, then click on the __Contrasts & F-Tests__ button. Select as many contrasts and F tests as you need. In most cases, you will want to work with the **Original EVs**. Any EV for which you want to evaluate a main effect should have a **1**, with all others **0**. If you want a contrast between two EVs, mark one **-1** and the other **1**.  


===== Running First-level Analyses =====
  * In the GUI, click the **Save** button.
Save the *.fsf file as template.fsf in the directory of your choice. 

  * In the GUI, click the **Go** button.
A new GUI window, **FEAT Watcher**, will open to provide progress updates.


====== III. Writing a batch script for FSL ======
If you have a lot of subjects or many runs to do the same analysis to, you may want to run a batch script to avoid tediously running the the rather slow FSL GUI.  Batch scripts should be written on golgi using nedit.  They use the bash scripting language that golgi uses.  before you start it is recommended you read a little on bash scripting [[http://pegasus.rutgers.edu/~elflord/unix/bash-tute.html|here]]. 
This script will run FEAT analysis, but requires 1)converted anat and func files and 2) a template. See [[biac:fsl:guide#I.Preparing for FSL|I.Preparing for FSL]] for file conversion. Example template shown below in this section.  This script would read a template file, and replace the anat/output/data directories, then run feat. This script would be for running the analysis on the machine you are currently logged in to ... it would not be for submitting the the gridengine. For example cluster scripts see: [[biac:cluster:examples|BIAC Cluster Sample Scripts]]

Here's a sample **batchFSL** script: 

<code bash>#!/bin/bash
#for each subject you will have to modify this script for the number of runs and
#the subject number

#loads the fsl program
export FSLDIR=/usr/local/packages/fsl
.  ${FSLDIR}/etc/fslconf/fsl.sh

#change this part
SUBJ=$1
EXPDIR=`findexp Reward.01`
FSLDATADIR=${EXPDIR}/Data/FSL/${SUBJ}
ANATFILE=${FSLDATADIR}/anat_brain.nii
 
#########

#makes the orient file
for run in 01 02 03 04; do
 OUTPUT=${FSLDATADIR}/run${run}_output
 DATA=${FSLDATADIR}/run${run}.hdr
 echo $OUTPUT
 #makes the fsf files from the template fsf file
 for i in 'template.fsf'; do
  sed -e 's@OUTPUT@'$OUTPUT'@g' \
   -e 's@ANAT@'$ANATFILE'@g' \
   -e 's@DATA@'$DATA'@g' <$i> ${FSLDATADIR}/FEAT_${run}.fsf
 done
 #runs the analysis using the newly created fsf file
 feat ${FSLDATADIR}/FEAT_${run}.fsf
done
</code>
===== making a template .fsf file =====
when making a batch file, you need to have a template file that has the outline for your FEAT analysis.
  - first open up FEAT using the directions on this page and set up an analysis.  This should include a model set-up, etc.  
  -Press **go** to run a trial run to make sure that the template works.  If it starts up without errors, save it in your FSL directory as **template.fsf**. 
  - close fsl
  - You can stop the test analysis by typing **killall** into the golgi window. However, It may be preferable to let the test analysis run all the way through, so you can see if the results (especially registration) turned out OK or not.
  - change directory to your FSL output directory
  - open your template file with gedit: **gedit template.fsf &**
  - You will now have to go through the template file and find all of the places where there will be variations between subjects and between runs.  Usually you will need to change most of the file names in the script.  These often include the output directory, the 4D data .hdr file, the anatomical image, and the files used for your model set-up when using the 3-column design.  
  - when you find one of these places in the .fsf file, replace the filename or number with a word, as marker.  This word should be in all caps, so that it doesn't match any of the other words in the file.  Also, be sure to leave the quotes around filenames there, only replace the path.
  - It will be helpful for later if you write down somewhere what you have changed, and what the marker words were
  - Repeat steps 7 and 8 until every place in the template file that you have marked all the relevant places in the template file

===== making the batch script =====
Now you need to make a batch file that uses the template file to run your various analyses.  This tutorial will mostly use the example code above, so you may want to open a second window to view the code side-by-side with the instructions. These instructions assume you have named your batch file **batchFSL**
  - the first thing you need to know is that all of the lines with a **#** at the beginning are comments
  - the first line **#!/bin/bash** doesn't execute, but it tells nedit that the script is a bash script, so nedit can highlight it properly.  
  - the first two non-comments basically tell UNIX about the feat command and other fsl commands so that when you call those commands, UNIX knows where to look
  - the next line **SUBJ=$1** is a variable assignment. $1 refers to the first command line argument, so if you typed **./batchFSL 30933** into the command line then 30933 would be the value of SUBJ. If you later want to refer to a variable, as is done in the next line, type along and whenever you get to a variable name put a **$** in front to refer to the variable. If using nedit, the variable name will turn blue when you do this.  
    * just like everything else in UNIX, variable names are case-sensitive
    * sometimes UNIX won't know when your variable name ends.  You will notice there is a problem when nedit continues to highlight things blue after the variable name ends.  To avoid confusion, you may want to put curly braces **{}** around your variable names.  
  - now set up a FSLDATADIR variable like the one in the example code.  This will make your code neater and avoid a lot of errors
  - you will now want to set up a loop that repeats for each of your runs.  It will look like the outer one in the example code.  It creates a variable called run, which you can refer to inside your loop
  - now, remember those markers you set up in the template.fsf file?  For each one of those, you will need to make a variable that will replace it.  If the variable will change for each run, put it inside the loop.  Otherwise put it outside.
  - The line **echo $OUTPUT** in the example code prints out to the screen the output directory.  This just helps the user know how far along the program is.  You should probably include some sort of marker to let the user know how many analyses have been completed.
  - now that you've set up variables for each of the markers in the template.fsf file, you will need to put those variables into the file.  The //sed command// helps with this.  I'm not sure why it is in a loop, but you can ask chris petty if you're curious.  This code is a revised version of something he wrote.  The sed program has many functions, but here we only need it to find the markers in the template.fsf file and replace them with the necessary text.
  - so, start out by copying the inner loop.  If you already copied it when you copied the outer loop, then don't copy it again.  
  - the **-e** flag tells the sed program to use it's find and replace command, so the text after that will tell sed what to find, and what to replace it with. The **s@**, **@** and **@g** are all markers to the sed program.  Don't remove them.   If you have more variables than are in the example code, just copy one of the middle lines into your code.  Make sure to leave the backslash(\) there, as it tells UNIX that the line isn't done. 
  - The marker names (the ones you put in the template.fsf file) are in red in the example code.  They will show up green in nedit.  Replace these (not the **@** symbols) with the markers you used in your template.fsf file
  - Now replace the words in blue with your variable names.  
  - leave the **<$i>** as is.  If you want to put your FEAT files to be named something other than FEAT_01.fsf, FEAT_02.fsf, etc, feel free to change the last argument however you want.  sed will save your file over any files that already exist, so if you want backup files, be sure to save them as something else before running this batch script.
  - now that sed has made/updated your .fsf files, you need to run your analysis on them, which is exactly what the second to last line does.  If you changed the names of the output files from sed, make sure that you also change the input to the feat command.  Otherwise your program will try to run analyses that don't exist.



====== V. Setting up Second-Level Analyses ======

  * Type **fsl**. Click **FEAT**.
  * Change the top left pull-down menu to **Higher-level analysis**.
  * Select the __Data__ tab. The top menu should read **Inputs are lower-level FEAT directories**. For __Number of analyses__, select the number of runs. Click **Select FEAT directories** and then select the directories at left (i.e., not the files). Note that you can select one and then copy and paste for the rest, changing the run numbers manually. Click **OK**. __Use lower-level copes__ will appear and all runs should be highlighted.
  * Select the _Stats_ tab. The top menu should read **Mixed effects: Flame 1**.
  * Click on **Model setup wizard**. Select **single group average**. Click **process**. Close the little __Model__ window that pops up. 
  * Click on **Full Model Setup**. You should have one row per run, and one column labeled EV1, with all **1**s in it. Click **Done**. (Note that you can skip the previous step, and just manually set everything to **1** in this step.)
  * Click **Save**. Type **FEAT_across** into the __Selection__ box. Click **OK**.
  * Click **Go**.

Your new analyses will be saved in a new directory called **across_runs.gfeat**.

There is a good description of concepts behind higher-level analyses on the [[http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FEAT/UserGuide#Setting_Up_Higher-Level_Analysis_in_FEAT|feat higher level analyis]].