Hoffman2:FSL: Difference between revisions
No edit summary |
(add fsl gpu example) |
||
(15 intermediate revisions by 4 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 | * [[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 21: | Line 21: | ||
DISPLAY is not set. Please set your DISPLAY environment variable! | DISPLAY is not set. Please set your DISPLAY environment variable! | ||
It means you did not open X11 along with your ssh connection. | It means you did not open X11 along with your ssh connection. See [[Hoffman2:Accessing_the_Cluster#GUI-Enabled_SSH_.5BRecommended.5D | here]] for more information. | ||
Line 57: | Line 56: | ||
| FMRIB's Automated Segmentation Tool - brain segmentation (into different tissue types) and bias field correction. | | FMRIB's Automated Segmentation Tool - brain segmentation (into different tissue types) and bias field correction. | ||
|- | |- | ||
| [http://www.fmrib.ox.ac.uk/fsl/first/index.html | | [http://www.fmrib.ox.ac.uk/fsl/first/index.html 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. | | 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. | ||
|} | |} | ||
Line 103: | Line 102: | ||
| Interactive display tool for 3D and 4D data. | | Interactive display tool for 3D and 4D data. | ||
|} | |} | ||
Line 124: | 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 129: | ||
FSL_SUB | FSL_SUB | ||
<!-- DMM --> | |||
<!--==switch_fsl== | |||
After you have [[Hoffman2:Profile | properly configured your profile]] so you have access to FSL and the other FMRI tools on Hoffman2, you also have access to the handy <code>switch_fsl</code> 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 [[Hoffman2:Scripts:switch_fsl | 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 <code>NO_FSL_JOBS=true</code> 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 | |||
#[[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 | |||
#*<code>qrsh -l h_rt=3:00:00,h_data=4G</code> | |||
#Set the environment variable | |||
#*<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''' | |||
#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 <code>chmod 750</code> to make the script executable | |||
chmod 750 myshellscript.sh | |||
Submit the shell script [[Hoffman2:Submitting_Jobs|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== | ==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
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
- SSH into the cluster
- Check out an interactive node with the necessary time and memory
qrsh -l h_rt=3:00:00,h_data=4G
- Set the environment variable
export NO_FSL_JOBS=true
- 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.
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
- Official FSL website http://www.fmrib.ox.ac.uk/fsl/