This shows you the differences between two versions of the page.
biac:fsl:guide [2012/12/12 17:59] petty [V. Setting up Second-Level Analyses] |
biac:fsl:guide [2023/02/23 18:43] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Using FSL ====== | ||
- | For reference, the FSL-FEAT analysis guide is available at [[http:// | ||
- | |||
- | 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: | ||
- | |||
- | ===== Logging in to the Cluster ===== | ||
- | [[biac: | ||
- | |||
- | |||
- | ===== 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: | ||
- | - 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. | ||
- | - **nifti.gz formatted anat and func** files in LAS orientation | ||
- | - An **anat_brain.nii.gz**, | ||
- | - A **template.fsf**, | ||
- | - A **batchFSL** script, again a Unix script, but this one defines input and output directories, | ||
- | |||
- | ===== Instructions ===== | ||
- | * Unordered List Item Change to the functional directory: | ||
- | < | ||
- | cd `findexp Poker.01` | ||
- | cd Data/ | ||
- | # 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 ../ | ||
- | # ../ 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 " | ||
- | * 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: | ||
- | * 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. | ||
- | This script will run FEAT analysis, but requires 1)converted anat and func files and 2) a template. See [[biac: | ||
- | |||
- | Here's a sample **batchFSL** script: | ||
- | |||
- | <code 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=/ | ||
- | . ${FSLDIR}/ | ||
- | |||
- | #change this part | ||
- | SUBJ=$1 | ||
- | EXPDIR=`findexp Reward.01` | ||
- | FSLDATADIR=${EXPDIR}/ | ||
- | ANATFILE=${FSLDATADIR}/ | ||
- | |||
- | ######### | ||
- | |||
- | #makes the orient file | ||
- | for run in 01 02 03 04; do | ||
- | | ||
- | | ||
- | echo $OUTPUT | ||
- | # | ||
- | for i in ' | ||
- | sed -e ' | ||
- | -e ' | ||
- | -e ' | ||
- | done | ||
- | #runs the analysis using the newly created fsf file | ||
- | feat ${FSLDATADIR}/ | ||
- | 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. | ||
- | - first open up FEAT using the directions on this page and set up an analysis. | ||
- | -Press **go** to run a trial run to make sure that the template works. | ||
- | - 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. | ||
- | - when you find one of these places in the .fsf file, replace the filename or number with a word, as marker. | ||
- | - 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. | ||
- | - the first thing you need to know is that all of the lines with a **#** at the beginning are comments | ||
- | - the first line **# | ||
- | - 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 **./ | ||
- | * 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. | ||
- | - 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. | ||
- | - 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. | ||
- | - 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. | ||
- | - Now replace the words in blue with your variable names. | ||
- | - leave the **< | ||
- | - now that sed has made/ | ||
- | |||
- | |||
- | |||
- | ====== V. Setting up Second-Level Analyses ====== | ||
- | |||
- | * Bring up a Golgi window in F-Secure SSH. | ||
- | * **cd / | ||
- | * 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:// | ||
- | |||
- | ======= VI.Remaining Questions & Problems ======= | ||
- | |||
- | Intermittent crashes on golgi, often suggesting an "out of memory" | ||
- | |||
- | |||
- | |||
- | ===== 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 " | ||
- | |||
- | ===== 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 / | ||
- | |||
- | == ORIENT in template.fsf == | ||
- | The last section of the template.fsf should read as follows: | ||
- | |||
- | < | ||
- | # 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 in batchFSL == | ||
- | |||
- | * Before the **for** loop in the batch script begins, paste the following line: | ||
- | |||
- | < | ||
- | / | ||
- | ORIENT=$FSLDATADIR/ | ||
- | |||
- | * You will also need to define the variable name **ORIENT** in your sed list: | ||
- | < | ||
- | |||
- | |||
- | ===== 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. | ||
- | * 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 [[biac: | ||
- | === 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. | ||
- | * 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' | ||
- | * 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. | ||
- | * Problem: the run stopped, saying the problem was possibly golgi ran out of memory | ||
- | * Solution: |