Difference between revisions of "FSL"

From UFRC
Jump to navigation Jump to search
m (Text replacement - "#uppercase" to "uc")
(14 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
==Home Website==
+
[[Category:Software]][[Category:Bioinformatics]][[Category:Neurology]]
−
[http://www.fmrib.ox.ac.uk/fsl/ Website]
+
{|<!--CONFIGURATION: REQUIRED-->
−
==HPC Installation==
+
|{{#vardefine:app|fsl}}
−
The FSL software on the cluster is located in the following directory:
+
|{{#vardefine:url|http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSL}}
−
/apps/fsl/3.3
+
<!--CONFIGURATION: OPTIONAL (|1}} means it's ON)-->
 +
|{{#vardefine:conf|}}          <!--CONFIGURATION-->
 +
|{{#vardefine:exe|1}}            <!--ADDITIONAL INFO-->
 +
|{{#vardefine:pbs|}}            <!--PBS SCRIPTS-->
 +
|{{#vardefine:policy|}}        <!--POLICY-->
 +
|{{#vardefine:testing|}}      <!--PROFILING-->
 +
|{{#vardefine:faq|}}            <!--FAQ-->
 +
|{{#vardefine:citation|1}}      <!--CITATION-->
 +
|{{#vardefine:installation|}} <!--INSTALLATION-->
 +
|}
 +
<!--BODY-->
 +
<!--Description-->
 +
{{#if: {{#var: url}}|
 +
{{App_Description|app={{#var:app}}|url={{#var:url}}|name={{#var:app}}}}|}}
  
−
This is actually a symbolic link to the most recent minor version of FSL, which as of July 2nd, 2007 was 3.3.11.
+
FSL is a comprehensive library of analysis tools for FMRI, MRI and DTI brain imaging data.
 +
<!--Modules-->
 +
==Required Modules==
 +
===Serial===
 +
* {{#var:app}}
 +
<!--
 +
===Parallel (OpenMP)===
 +
* intel
 +
* {{#var:app}}
 +
===Parallel (MPI)===
 +
* intel
 +
* openmpi
 +
* {{#var:app}}
 +
-->
 +
==System Variables==
 +
* HPC_{{uc:{{#var:app}}}}_DIR - installation directory
 +
* HPC_{{uc:{{#var:app}}}}_BIN - executable directory
 +
<!--Configuration-->
 +
{{#if: {{#var: conf}}|==Configuration==
 +
See the [[{{PAGENAME}}_Configuration]] page for {{#var: app}} configuration details.
 +
|}}
 +
<!--Run-->
 +
{{#if: {{#var: exe}}|==Additional Information==
 +
|}}
 +
===Running bedpostx===
 +
* Log into dev1 or dev2.
 +
* Run '<code>screen</code>' and turn the screen log onto monitor the run
 +
ctrl+a shift+h
 +
The name of the log file will be displayed in your terminal.
 +
* Load the fsl module
 +
module load fsl
 +
* Run <code>bedpostx</code>, a typical minimal command should look like
 +
bedpostx datadir -M emailaddr
 +
* You may detach the screen at any time and then use screen -r to reattach at a later time.
 +
* Once the <code>bedpostx</code> script has finished running turn the screen log off with 
 +
ctrl+a shift+h
 +
* Look at the bedpostx output in the screen log and in your email for job warning or error notifications.
  
−
If you are going to be using the FSL software on the cluster, there are some things you will need to do first.
+
;Available bedpostx options
 +
The bedpostx script has been modified to work with Moab/Torque for job submissions. In addition to the standard bedpostx command line options, the following Moab/Torque options have been added:
  
−
* For bash shell users:
+
{| class="wikitable"
−
<pre>
+
|-
−
$ export FSLDIR=/apps/fsl/3.3
+
! Option !! Default Value !! Description
−
$ . ${FSLDIR}/etc/fslconf/fsl.sh
+
|-
−
$ export PATH=${FSLDIR}/bin:${PATH}
+
| -m || abe || see qsub. Note: slice job mail options are set to 'a' to avoid email overload
−
</pre>
+
|-
−
* For tcsh shell users:
+
| -M || || see qsub. Note: you must provide an email address (REQUIRED)
−
<pre>
+
|-
−
$ setenv FSLDIR /apps/fsl/3.3
+
| -N || pbx || job name prefix. Note: this is followed by _pre, _slice, and _post
−
$ source ${FSLDIR}/etc/fslconf/fsl.csh
+
|-
−
$ setenv PATH ${FSLDIR}/bin:${PATH}
+
| -ws || 4:00:00 || see qsub -l walltime. Applies to all slice processing jobs
−
</pre>
+
|-
−
If you are going to be using FSL on an on-going basis, it might be a good idea to place these commands into your start-up scripts. Just put these commands into .bashrc (for bash) or .cshrc (for tcsh) in your home directory.
+
| -wp || 1:00:00 || see qsub -l walltime. Applies to pre and post processing jobs
 +
|-
 +
| -ms || 1gb || see qsub -l pmem. Applies to all slice processing jobs
 +
|-
 +
| -mp || gb || see qsub -l pmem. Applies to all pre and post processing jobs
 +
|-
 +
| -v || || &nbsp;turns on verbose option, i.e. displays additional information
 +
|}
  
−
==Official Documentation==
+
;How bedpostx is run:
−
[http://www.hpc.ufl.edu/doc/fsl/index.html FSL Documentation]
+
* A directory will be created for the output data. It will be named using the original data folder name followed by '<code>.bedpostX</code>'.
 +
* Only one bedpostx script at a time can be run for a given data directory otherwise the output data will be unreliable.
 +
* If you run bedpostx and the output directory already exists, beedpostx will look to see if any slices need to be processed. It will then run jobs for all the unprocessed slices and post-process all the slice data.
 +
* There are 3 stages in the execution of bedpostx:
 +
#pre-processing. To view job status use: qstat -u yourusername
 +
#slice processing. A job is posted for each individual slice as part of a job array. To view individual job status use: '<code>qstat -t -u yourusername</code>'.
 +
#post-processing. To view job status use: '<code>qstat -u yourusername</code>'
 +
 
 +
;Notes:
 +
* If you are sure that the terminal will not be disconnected at any time while running the bedpostx script then you don't need to use screen. You can not allow the terminal from which you run bedpostx to get disconnected while the script is running. If the terminal is disconnected, it will cause the job array completion detection to fail and the post processing will run before the slice processing is finished. This is why using screen is recommended.
 +
* If you need to cancel an on-going bedpostx run you can execute the '<code>cancel</code>' command from the created output data directory by typing ./cancel or by using the full path to the command. You must execute cancel from the same server where you originally started bedpostx. The cancel command will display the bedpostx PID in case you want to run '<code>ps aux | grep yourusername</code>' and make sure that the PID matches your bedpostx process. It may take up to 30 seconds for bedpostx to handle the request. If you run bedpostx after previously cancelling it, you may either leave the existing output data directory in place or manually delete it to start from scratch. If you do not delete the directory and there are some slices that were previously processed, they will not be processed again. The cancel command will delete itself once it's executed.
 +
* Be aware that the job array numbers do not match the sub-directory numbers in the diff_slices directory. The jobs are always numbered 1-n and the directory numbers 0-(n-1) the first time you run bedpostx. If you were to rerun bedpostx again with some slices already processed in a prior run, then the only way to match job numbers with sub-directory numbers is via the job control file commands.txt.
 +
 
 +
<!--PBS scripts-->
 +
{{#if: {{#var: pbs}}|==PBS Script Examples==
 +
See the [[{{PAGENAME}}_PBS]] page for {{#var: app}} PBS script examples.
 +
|}}
 +
<!--Policy-->
 +
{{#if: {{#var: policy}}|==Usage Policy==
 +
WRITE USAGE POLICY HERE (Licensing, usage, access).
 +
|}}
 +
<!--Performance-->
 +
{{#if: {{#var: testing}}|==Performance==
 +
WRITE_PERFORMANCE_TESTING_RESULTS_HERE
 +
|}}
 +
<!--Faq-->
 +
{{#if: {{#var: faq}}|==FAQ==
 +
*'''Q:''' **'''A:'''|}}
 +
<!--Citation-->
 +
{{#if: {{#var: citation}}|==Citation==
 +
If you publish research that uses {{#var:app}} you have to cite it as follows:
 +
 
 +
#M. Jenkinson, C.F. Beckmann, T.E. Behrens, M.W. Woolrich, S.M. Smith. FSL. NeuroImage, 62:782-90, 2012
 +
#M.W. Woolrich, S. Jbabdi, B. Patenaude, M. Chappell, S. Makni, T. Behrens, C. Beckmann, M. Jenkinson, S.M. Smith. Bayesian analysis of neuroimaging data in FSL. NeuroImage, 45:S173-86, 2009
 +
#S.M. Smith, M. Jenkinson, M.W. Woolrich, C.F. Beckmann, T.E.J. Behrens, H. Johansen-Berg, P.R. Bannister, M. De Luca, I. Drobnjak, D.E. Flitney, R. Niazy, J. Saunders, J. Vickers, Y. Zhang, N. De Stefano, J.M. Brady, and P.M. Matthews. Advances in functional and structural MR image analysis and implementation as FSL. NeuroImage, 23(S1):208-19, 2004
 +
|}}
 +
<!--Installation-->
 +
{{#if: {{#var: installation}}|==Installation==
 +
See the [[{{PAGENAME}}_Install]] page for {{#var: app}} installation notes.|}}
 +
<!--Turn the Table of Contents and Edit paragraph links ON/OFF-->
 +
__NOTOC____NOEDITSECTION__
 +
=Validation=
 +
* Validated 4/5/2018

Revision as of 21:20, 6 December 2019

Description

fsl website  

FSL is a comprehensive library of analysis tools for FMRI, MRI and DTI brain imaging data.

Required Modules

Serial

  • fsl

System Variables

  • HPC_FSL_DIR - installation directory
  • HPC_FSL_BIN - executable directory

Additional Information

Running bedpostx

  • Log into dev1 or dev2.
  • Run 'screen' and turn the screen log onto monitor the run
ctrl+a shift+h

The name of the log file will be displayed in your terminal.

  • Load the fsl module
module load fsl
  • Run bedpostx, a typical minimal command should look like
bedpostx datadir -M emailaddr
  • You may detach the screen at any time and then use screen -r to reattach at a later time.
  • Once the bedpostx script has finished running turn the screen log off with
ctrl+a shift+h
  • Look at the bedpostx output in the screen log and in your email for job warning or error notifications.
Available bedpostx options

The bedpostx script has been modified to work with Moab/Torque for job submissions. In addition to the standard bedpostx command line options, the following Moab/Torque options have been added:

Option Default Value Description
-m abe see qsub. Note: slice job mail options are set to 'a' to avoid email overload
-M see qsub. Note: you must provide an email address (REQUIRED)
-N pbx job name prefix. Note: this is followed by _pre, _slice, and _post
-ws 4:00:00 see qsub -l walltime. Applies to all slice processing jobs
-wp 1:00:00 see qsub -l walltime. Applies to pre and post processing jobs
-ms 1gb see qsub -l pmem. Applies to all slice processing jobs
-mp gb see qsub -l pmem. Applies to all pre and post processing jobs
-v  turns on verbose option, i.e. displays additional information
How bedpostx is run
  • A directory will be created for the output data. It will be named using the original data folder name followed by '.bedpostX'.
  • Only one bedpostx script at a time can be run for a given data directory otherwise the output data will be unreliable.
  • If you run bedpostx and the output directory already exists, beedpostx will look to see if any slices need to be processed. It will then run jobs for all the unprocessed slices and post-process all the slice data.
  • There are 3 stages in the execution of bedpostx:
  1. pre-processing. To view job status use: qstat -u yourusername
  2. slice processing. A job is posted for each individual slice as part of a job array. To view individual job status use: 'qstat -t -u yourusername'.
  3. post-processing. To view job status use: 'qstat -u yourusername'
Notes
  • If you are sure that the terminal will not be disconnected at any time while running the bedpostx script then you don't need to use screen. You can not allow the terminal from which you run bedpostx to get disconnected while the script is running. If the terminal is disconnected, it will cause the job array completion detection to fail and the post processing will run before the slice processing is finished. This is why using screen is recommended.
  • If you need to cancel an on-going bedpostx run you can execute the 'cancel' command from the created output data directory by typing ./cancel or by using the full path to the command. You must execute cancel from the same server where you originally started bedpostx. The cancel command will display the bedpostx PID in case you want to run 'ps aux | grep yourusername' and make sure that the PID matches your bedpostx process. It may take up to 30 seconds for bedpostx to handle the request. If you run bedpostx after previously cancelling it, you may either leave the existing output data directory in place or manually delete it to start from scratch. If you do not delete the directory and there are some slices that were previously processed, they will not be processed again. The cancel command will delete itself once it's executed.
  • Be aware that the job array numbers do not match the sub-directory numbers in the diff_slices directory. The jobs are always numbered 1-n and the directory numbers 0-(n-1) the first time you run bedpostx. If you were to rerun bedpostx again with some slices already processed in a prior run, then the only way to match job numbers with sub-directory numbers is via the job control file commands.txt.



Citation

If you publish research that uses fsl you have to cite it as follows:

  1. M. Jenkinson, C.F. Beckmann, T.E. Behrens, M.W. Woolrich, S.M. Smith. FSL. NeuroImage, 62:782-90, 2012
  2. M.W. Woolrich, S. Jbabdi, B. Patenaude, M. Chappell, S. Makni, T. Behrens, C. Beckmann, M. Jenkinson, S.M. Smith. Bayesian analysis of neuroimaging data in FSL. NeuroImage, 45:S173-86, 2009
  3. S.M. Smith, M. Jenkinson, M.W. Woolrich, C.F. Beckmann, T.E.J. Behrens, H. Johansen-Berg, P.R. Bannister, M. De Luca, I. Drobnjak, D.E. Flitney, R. Niazy, J. Saunders, J. Vickers, Y. Zhang, N. De Stefano, J.M. Brady, and P.M. Matthews. Advances in functional and structural MR image analysis and implementation as FSL. NeuroImage, 23(S1):208-19, 2004


Validation

  • Validated 4/5/2018
Retrieved from "https://help.rc.ufl.edu/mediawiki/index.php?title=FSL&oldid=18918"