User Tools

Site Tools


biac:fsl:guide

This is an old revision of the document!


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.

  1. Converting data files to format used by FEAT (Section I).
  2. Setting up a model and running first level analysis with FEAT (Section II).
  3. Writing batch and template scripts (Section III).
  4. Running MELODIC for Independent Components Analysis (Section IV).
  5. Running second level FEAT (Section V).
  6. Troubleshooting & Problems (VI).

Parts I-II can be done individually or by making a batch script. Instructions to batch file conversions are here. Instructions for batching FEAT analysis are in III. Writing a batch script for FSL.

Logging in to the Cluster

Accessing your 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:

  1. 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 :)
  2. nifti.gz formatted anat and func files in LAS orientation
  3. An anat_brain.nii.gz, which you get by running BET on your nifti anats
  4. A template.fsf, which is a really long Unix script that describes your full analysis model
  5. 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:
 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
 
    
* Convert the functional data to NIFTI format in LAS orientation:
  bxhreorient --orientation=LAS run004_01.bxh run01
  #the default output type of most bxh-tools is .nii.gz
  • This will create run01.nii.gz and run01.bxh
  • Change to the anatomical directory
  cd ../../Anat/20050929_30933/series002
  # ../ means go back 1 directory, so ../../ is going up 2 directories to Data
  • Convert the anatomical data to NIFTI format in LAS:
  bxhreorient --orientation=LAS series002.bxh anat
  • 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

  1. 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).

  1. 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.
  2. In the GUI, go to the Stats tab. Use FILM prewhitening should be checked. For Add motion parameters to model you should select No.
  3. 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 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 here. This script will run FEAT analysis, but requires 1)converted anat and func files and 2) a template. See I.Preparing for FSL for file conversion. Example template shown below in this section. Here's a sample batchFSL script:

#!/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
FSLDATADIR=~/net/katz/data/Reward.01/Data/FSL/$SUBJ
ANATFILE=${FSLDATADIR}/anatb.nii
 
#########
 
#makes the orient file
/home/gadde/bin/MkFlirtInitMtx.pl --in $FSLDATADIR/run02.bxh --stdref --o $FSLDATADIR/ORIENT.mat
ORIENT=$FSLDATADIR/ORIENT.mat
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@ORIENT@'$ORIENT'@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

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.

  1. first open up FEAT using the directions on this page and set up an analysis. This should include a model set-up, etc.
  2. 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.
  3. close fsl
  4. 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.
  5. change directory to your FSL output directory
  6. open your template file with gedit: gedit template.fsf &
  7. 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.
  8. 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.
  9. It will be helpful for later if you write down somewhere what you have changed, and what the marker words were
  10. 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

  1. the first thing you need to know is that all of the lines with a # at the beginning are comments
  2. 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.
  3. 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
  4. 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.
  5. 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
  6. 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
  7. 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.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
  12. 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
  13. Now replace the words in blue with your variable names.
  14. 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.
  15. 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

  • Bring up a Golgi window in F-Secure SSH.
  • cd /home/huettel/net/goldman/data/BIAC/Poker.01/data/FSL/31625, or whatever directory you want to analyze.
  • 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 1s 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 feat web manual.

VI.Remaining Questions & Problems

Intermittent crashes on golgi, often suggesting an “out of memory” error.

Registration

Registration is very poor for many of the spiral images

  • Should we correct for maximum image intensity in some way?
  • Do we use ORIENT files? Registration seems dubious.

It may be the case that if there is less than 120mm in any direction, then it will pop up the “partial FOV” error. That would be the case if we had relatively few slices or if the size of slizes were misrepresented.

Using ORIENT Files

The ORIENT file created by Syam Gyadde seems to give better registration results for data acquired with both spiral and EPI sequences. The file is a .mat file located in /home/gadde/bin/MkFlirtInitMtx.pl on Golgi, and it needs to be appropriately inserted once into the template.fsf script and several times into the batchFSL script.

ORIENT in template.fsf

The last section of the template.fsf should read as follows:

# Now options that don't appear in the GUI
# Alternative example_func image (not derived from input 4D dataset)
set fmri(alternative_example_func) ""

# Delete GLM residuals?
set fmri(cleanup_residuals_yn) 1

# Initial structural space registration initialisation transform
set fmri(init_initial_highres) ""

# Structural space registration initialisation transform
set fmri(init_highres) ""

# Standard space registration initialisation transform
set fmri(init_standard) "ORIENT"
ORIENT in batchFSL
  • Before the for loop in the batch script begins, paste the following line:
#to convert from bxhheader to nifti  look in the fileconverter file in this directory
/home/gadde/bin/MkFlirtInitMtx.pl --in $FSLDATADIR/run2.bxh --stdref --o $FSLDATADIR/ORIENT.mat
ORIENT=$FSLDATADIR/ORIENT.mat
  • You will also need to define the variable name ORIENT in your sed list:
-e 's@ORIENT@'$ORIENT'@g' \

MELODIC ICA

Second-level Analyses

Troubleshooting

Registration problems:

  • Problem: the data is being registered as a large, stretched-out brain, going way beyond the bounds of a normal brain
    • Solution: check the .bxh header files for your original functional data. The scanner has recently been putting out functional images with voxel sizes for anatomical images. change the x and y spacing to 3.75
  • Problem: the brain is being flipped so that the frontal lobe is near the cerebellum
    • Solution: run a BET brain extraction on the anatomical data. See step 5 in the preparing for fsl section on how to do this

FEAT errors

  • Problem: while running a batch script, all of the FEAT windows pop up at once even though the script is supposed to run them sequencially
    • Solution: open the script using nedit and find the line that starts with feat followed by some input files. If there is an ampersand(&) at the end of that line, remove it and the process will be run sequencially. If that doesn't solve the problem, the FEAT windows should be putting out an error
  • Problem: when running a batch script, the FEAT Watcher says that the number of volumes is 0
    • Solution: your script is pointing to a file that doesn't exist. Open the FSL GUI and load the .fsf file that your script just created. If Danny wrote the script, it's located under the subject folder, called
      FEAT_(runnumber).fsf e.g., FEAT_1.fsf. Look at your 4D data files and find the .hdr files that were supposed to be analyzed.
  • Problem: when running a batch script, the FEAT Watcher says that the number of volumes is incorrect (not 0, see above)
    • Solution: the batch script is most likely using a template file that assumes that all of your runs have the same number of time points. If one of the runs has a different number of time points, open the GUI, load your .fsf file. The GUI will update the number of volumes automatically, so now you just hit go. If the analysis still doesn't work, then ask scott or chris petty.
  • Problem: the run stopped, saying the problem was possibly golgi ran out of memory
    • Solution:
biac/fsl/guide.1355334797.txt.gz · Last modified: 2014/08/04 16:03 (external edit)