Hoffman2:FSL

From Center for Cognitive Neuroscience
Jump to navigation Jump to search

Back to all things Hoffman2

FSL is a comprehensive library of analysis tools for FMRI, MRI and DTI brain imaging data. FSL is written mainly by members of the Analysis Group, FMRIB, Oxford, UK.


Multiple versions are maintained on the Hoffman2 cluster to allow researchers to be consistent in using the same version for data analysis within a single study. You can either:

  • do nothing, and always use the "current" version of FSL on the cluster
  • actively choose which version of FSL you would like to run

We recommend the latter for data integrity and reproducibility.


FSL GUI

Make sure you source the FMRI Path in your Profile before doing anything, or else you won't be able to access FSL.


To run FSL using a GUI on hoffman2, use the following command:

$ fsl &

If you received this message while opening FSL

 DISPLAY is not set. Please set your DISPLAY environment variable!

It means you did not open X11 along with your ssh connection. See here for more information.


FSL TOOLS

A complete list of tools can be found here

Functional MRI (command line only)

Tool Explanation
feat Model-based FMRI analysis: data preprocessing (including MCFLIRT motion correction); first-level FILM GLM timeseries analysis; higher-level FLAME Bayesian mixed effects analysis.
melodic Model-free FMRI analysis using Probabilistic Independent Component Analysis (PICA). MELODIC automatically estimates the number of interesting noise and signal sources in the data and because of the associated "noise model", is able to assign significance ("p-values") to the output spatial maps. MELODIC can also analyse multiple subjects or sessions simultaneously using Tensor-ICA.
fabber Fast ASL & BOLD Bayesian Estimation Routine. Efficient nonlinear modelling and estimation of BOLD and CBF from dual-echo ASL data, using Variational Bayes.

Structural MRI (command line only)

Tool Explanation
bet Brain Extraction Tool - segments brain from non-brain in structural and functional data, and models skull and scalp surfaces.
fast FMRIB's Automated Segmentation Tool - brain segmentation (into different tissue types) and bias field correction.
first FMRIB's Integrated Registration and Segmentation Tool. FIRST uses mesh models trained with a large amount of rich hand-segmented training data to segment subcortical brain structures.

GUI Commands/Tools [Make sure to have X11 forwarding on]

Tool Explanation
fsl Bring you to the FSL menu where you can choose what type of analysis.
Fdt FMRIB's Diffusion Toolbox - tools for low-level diffusion parameter reconstruction and probabilistic tractography, including crossing-fibre modelling.
Flirt FMRIB's Linear Image Registration Tool - linear inter- and intra-modal registration.
Feat Model-based FMRI analysis: data preprocessing (including MCFLIRT motion correction); first-level FILM GLM timeseries analysis; higher-level FLAME Bayesian mixed effects analysis.
Featquery A program which allows you to interrogate FEAT results by defining a mask or set of co-ordinates (in standard-space, highres-space or loweres-space) and get mean stats values and time-series.
Glm A GUI for setting up just the design matrix and contrasts, in the same way as in FEAT, for use with other modelling/inference programs such as randomise.
Melodic Model-free FMRI analysis using Probabilistic Independent Component Analysis (PICA). MELODIC automatically estimates the number of interesting noise and signal sources in the data and because of the associated "noise model", is able to assign significance ("p-values") to the output spatial maps. MELODIC can also analyse multiple subjects or sessions simultaneously using Tensor-ICA.
Possum Physics-Oriented Simulated Scanner for Understanding MRI. An FMRI data simulator that produces realistic simulated images and FMRI time series given a gradient echo pulse sequence, a segmented object with known tissue parameters, and a motion sequence..
Renderhighres Transforms all thresholded stats images in a FEAT directory into high resolution or standard space and overlays these onto the high resolution or standard space images. This then produces PNG format pictures of the overlays and, by default, deletes the 3D AVW colour overlay images.
Renderstats This tool allows you to combine a background image (raw FMRI or high resolution MRI) image with one or two statistics images. The statistics image(s) must be in registration with the background image.
Susan Nonlinear noise reduction.
fslview Interactive display tool for 3D and 4D data.

Cluster

Scripts that self-submit
fdt feat first fslval possom randomise tbss
GUIs that self-submit Fdt Feat Flirt Possum

FSL_SUB


switch_fsl

After you have properly configured your profile so you have access to FSL and the other FMRI tools on Hoffman2, you also have access to the handy switch_fsl tool. It allows you to actively choose which version of FSL you use for analyses so you can stay locked into one version throughout a project before switching for a new project.

See its documentation here.



NO_FSL_JOBS

Sometimes FSL doesn't know how to allocate enough resources for its jobs properly. Specifically we have found the FEAT tool often unable to do this for group analyses or other complex tasks. So we did some tinkering with FSL to allow you to override its job submission on Hoffman2 and run it like it was just on your laptop. The trick is to set NO_FSL_JOBS=true in your environment and FSL will not submit jobs.


Interactive Session

If you want to watch FEAT run (kinda like paint drying, but to each their own), you can do the following

  1. SSH into the cluster
  2. Check out an interactive node with the necessary time and memory
    • qrsh -l i,time=3:00:00,mem=3G
  3. Set the environment variable
    • export NO_FSL_JOBS=true
  4. Run your FSL commands. This means not using qsub, or command files, but simply executing the FSL command
  5. The commands will just run and not submit any jobs.


Submitting a Job

If you don't want to watch FEAT run (why would you?), you can do the following

Create a shell script (e.g. myshellscript.sh) with the following contents

#!/bin/bash
export NO_FSL_JOBS=true
feat design.fsf
# any other FSL commands you want

And make sure to run chmod 755 to make the script executable

chmod 755 myshellscript.sh

Submit the shell script as a job but with the adequate time and memory allocations

qsub -l time=23:00:00,mem=4G -V -m bea -cwd /path/to/myshellscript.sh

And the FSL commands will be sent into the queue to run with your time and memory constraints rather than FSL's. This may take some playing with to get the time and memory allocations correct, but at least you have the ability to tweak them.



External Links