Hoffman2:FSL: Difference between revisions

From Center for Cognitive Neuroscience
Jump to navigation Jump to search
(add fsl gpu example)
 
(6 intermediate revisions by 2 users not shown)
Line 6: Line 6:
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:
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
* do nothing, and always use the "current" version of FSL on the cluster
* [[Hoffman2:FSL#switch_fsl|actively choose]] which version of FSL you would like to run
* [[Hoffman2:Modules#FSL|actively choose]] which version of FSL you would like to run
We recommend the latter for data integrity and reproducibility.
We recommend the latter for data integrity and reproducibility.
   
   
Line 102: Line 102:
| Interactive display tool for 3D and 4D data.
| Interactive display tool for 3D and 4D data.
|}
|}


==Cluster==
==Cluster==
Line 115: Line 116:
| [http://www.fmrib.ox.ac.uk/fsl/randomise/index.html randomise]
| [http://www.fmrib.ox.ac.uk/fsl/randomise/index.html randomise]
| [http://www.fmrib.ox.ac.uk/fsl/tbss/index.html tbss]
| [http://www.fmrib.ox.ac.uk/fsl/tbss/index.html tbss]
|-
! GUIs that self-submit
! GUIs that self-submit
| [http://www.fmrib.ox.ac.uk/fsl/fdt/index.html Fdt]
| [http://www.fmrib.ox.ac.uk/fsl/fdt/index.html Fdt]
Line 120: Line 122:
| [http://www.fmrib.ox.ac.uk/fsl/flirt/index.html Flirt]
| [http://www.fmrib.ox.ac.uk/fsl/flirt/index.html Flirt]
| [http://www.fmrib.ox.ac.uk/fsl/possum/index.html Possum]
| [http://www.fmrib.ox.ac.uk/fsl/possum/index.html Possum]
|-
|-
|-
|}
|}


Line 129: Line 134:


See its documentation [[Hoffman2:Scripts:switch_fsl | here]]. -->
See its documentation [[Hoffman2:Scripts:switch_fsl | here]]. -->


==NO_FSL_JOBS==
==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 <code>NO_FSL_JOBS=true</code> in your environment and FSL will not submit 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 <code>NO_FSL_JOBS=true</code> in your environment and FSL will not submit jobs.'''


===Interactive Session===
===Interactive Session===
Line 138: Line 143:
#[[Hoffman2:Accessing_the_Cluster#SSH_-_Command_Line|SSH]] into the cluster
#[[Hoffman2:Accessing_the_Cluster#SSH_-_Command_Line|SSH]] into the cluster
#Check out an [[Hoffman2:Interactive_Sessions|interactive node]] with the necessary time and memory
#Check out an [[Hoffman2:Interactive_Sessions|interactive node]] with the necessary time and memory
#*<code>qrsh -l i,time=3:00:00,mem=3G</code>
#*<code>qrsh -l h_rt=3:00:00,h_data=4G</code>
#Set the environment variable
#Set the environment variable
#*<code>export NO_FSL_JOBS=true</code>
#*<code>export NO_FSL_JOBS=true</code>
#Run your FSL commands. '''This means not using qsub, or command files, but simply executing the FSL command'''
#Run your FSL commands. '''This means not using qsub, or command files, but simply executing the FSL command'''
#The commands will just run and not submit any jobs.
#The commands will just run and not submit any jobs.


===Submitting a Job===
===Submitting a Job===
Line 154: Line 158:
  # any other FSL commands you want
  # any other FSL commands you want


And make sure to run <code>chmod 755</code> to make the script executable
And make sure to run <code>chmod 750</code> to make the script executable
  chmod 755 myshellscript.sh
  chmod 750 myshellscript.sh


Submit the shell script [[Hoffman2:Submitting_Jobs|as a job]] but with the adequate time and memory allocations
Submit the shell script [[Hoffman2:Submitting_Jobs|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
  qsub -l h_rt=23:00:00,h_data=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.
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.




==FSL GPU==
Some FSL tools, like ''eddy'' and ''bedpostx'', can utilize Hofmman's GPU architecture to speed up their processing times. Below is an example of how to request a CUDA 9.1-enabled GPU node.
# request Tesla P4 GPU node
qrsh -l gpu,P4,h_rt=5:00:00
module load cuda/9.1
module load fsl/6.0.4
export NO_FSL_JOBS=true
# now run eddy_cuda9.1 or bedpostx_gpu




==External Links==
==External Links==
* Official FSL website http://www.fmrib.ox.ac.uk/fsl/
* Official FSL website http://www.fmrib.ox.ac.uk/fsl/

Latest revision as of 19:56, 15 July 2022

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


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 h_rt=3:00:00,h_data=4G
  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 750 to make the script executable

chmod 750 myshellscript.sh

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

qsub -l h_rt=23:00:00,h_data=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.


FSL GPU

Some FSL tools, like eddy and bedpostx, can utilize Hofmman's GPU architecture to speed up their processing times. Below is an example of how to request a CUDA 9.1-enabled GPU node.

# request Tesla P4 GPU node
qrsh -l gpu,P4,h_rt=5:00:00

module load cuda/9.1
module load fsl/6.0.4
export NO_FSL_JOBS=true

# now run eddy_cuda9.1 or bedpostx_gpu


External Links