BrainFX FSL Customization

FSL must be customized for BrainFX use. The customization of FSL in FSLfx is gear towards BMU Data Standard for fMRI analysis.

It is important to note that we are not recreating FSL User Interface inside BrainFX. The modules imported might not be fully functional as in FSL User Interface. Most importantly, we do not intend to import all modules in FSL. Rather, we import on an as-needed basis.

With FSLfx, FSL is assumed to be a self-contained, sealed environment. With sealed, we mean you cannot change any FSL configuration parameters such as those in etc/fslconf/fsl.sh without expecting FSLfx to fail. We do not design it to work with your existing FSL installation.

FSLfx uses bash shell to call FSL.

BrainFX requires that your FSL program to be accessible via uk.ac.ox.fmrib.fsl.<os>_<version>/software/fsl. This is done either by

1. unzip your FSL package inside uk.ac.ox.fmrib.fsl.<os>_<version>/software/ directory. This should create the fsl directory and populate it appropriately.
2. symbolic link your existing FSL installation as uk.ac.ox.fmrib.fsl.<os>_<version>/software/fsl directory.

FSL configuration parameters are stored in fsl/fslconf/fsl.sh and <home>/.fslconf/fsl.sh where <home> is your home directory. FSLfx require them to be set to specific values.

FSLfx connects to FSL using the Bridge Pattern, i.e., file fslfx.sh. This bridge does overwrites values in .fslconf/fsl.sh. See fslfx.sh for more detail.

uk.ac.ox.fmrib.fsl.<os>_<version>/software/fslfx.sh is used by FSLfx to call FSL using the Bridge pattern. Its syntax is:

fsl.sh </absolute/path/to/FSLDIR> '<launch string>'

The first parameter must be the absolute path to the ‘fsl’ directory which is created when you unzip the FSL package. This will be the $FSLDIR as required by FSL. The <launch string> is is your command line to call FSL program, using $FSLDIR whenever you need to refer to FSL, and enclosed in single quotation ( ' ) to prevent <launch string> from being expanded (interpreted) by your command line.

fslfx.sh overwrites values in your .fslconf/fsl.sh and FSL/etc/fsl.sh. At present, it overwrites NIFTITYPE to NIFTI

Brain Extraction Tool (BET) : http://www.fmrib.ox.ac.uk/fsl/bet/index.html

Command Line :

BET (Brain Extraction Tool) v1.2 - FMRIB Analysis Group, Oxford

Usage: bet <input fileroot> <output fileroot> [options]

-o : generate brain surface outline overlaid onto original image
-m : generate binary brain mask
-s : generate approximate skull image
-n : don't generate segmented brain image output
-f <fractional_threshold> : fractional intensity threshold (0->1); 
     default=0.5; smaller values give larger brain outline estimates
-g <fractional_threshold> : vertical gradient in fractional intensity threshold (-1->1);
     default=0; positive values give larger brain outline at bottom, smaller at top
-t : apply thresholding to segmented brain image and mask
-c <x y z> : co-ordinates (mm not voxels) for centre of initial brain surface sphere
-r <r>: head radius (mm not voxels); initial surface sphere is set to half of this
-v : verbose text output

Note: it appears that on the command line, <input> <output> must come immediately after bet command.

Nonlinear Noise Reduction (SUSAN) : http://www.fmrib.ox.ac.uk/fsl/susan/index.html

command line :

susan_smooth <input> <bt> <output> <dt> <dim> <use_median> <n_usans> [<usan1> <bt1> [<usan2> <bt2>] <usanoutput>]

<bt> is brightness threshold and should be greater than noise level and less than contrast of edges to be preserved.
<dt> is spatial size (sigma) of smoothing, in mm.
<dim> is dimensionality (2 or 3), depending on whether smoothing is to be within-plane (2) or fully 3D (3).
<use_median> determines whether to use a local median filter in the cases where single-point noise is detected (0 or 1).
<n_usans> determines whether the smoothing area (USAN) is to be found from secondary images (0, 1 or 2).

FMRIB’s Automated Segmentation Tool

http://www.fmrib.ox.ac.uk/fsl/fast/index.html

Command line

FAST - FMRIB's Automated Segmentation Tool
FAST Version 3.53

Usage: fast [-options] imagefile 
options:
    -t<n>:      input image type. 1-T1, 2-T2, 3-PD (default T1)
    -c <n>:     number of classes (default 3)
    -a:         use apriori probability maps (for initialisation only)
    -A:         use apriori probability maps (for initialisation and for posteriors)
    -ap <prefix> | -Ap <prefix>:        path+filename prefix to pre-registered (to input data) 
                apriori probability maps, <prefix>_gm _wm and _csf (uncompressed Analyze format)
    -od <base>: output basename (default <input>)
    -os:        output segmentation with one class per image
    -op:        output probability maps (one for each class)
    -or:        output restored image
    -ob:        output bias correction field
    -n:         do not output segmentation
    -m <file>:  use file with starting values for the mean of each tissue
    -2:         2D segmentation (only for 3D images)
    -i <n>:     number of iterations (default 8)
    -l <n>:     iterations for bias correction field smoothing (default 100)
    -p:         disable automatic parameter updating
    -b <v>:     MRF neighbourhood beta value (default 0.3)
    -oba <n>:   output dilated bias correction field (n iterations)
    -e:         enable partial volume classification
    -ov:        output partial volume images (one for each class)
    --b <v>:    MRF beta value for PVE classification (default 1.5)
    --p:        disable parameter updating during PVE classification
    -v<n>:      verbose level (0-5; default 1)
    -h:         advanced options

Note:

1. This is equivalent to setting “Number of input channels” in FAST UI to 1, i.e. no multichannel segmentation.

Multispectral FMRIB Automated Segmentation Tool

http://www.fmrib.ox.ac.uk/fsl/fast/index.html (bottom of page)

command line:

MFAST - Multispectral FAST
MFAST Version 3.53

Usage: mfast [-options] channel1 channel2 ... 
options:
    -s <n>      number of input channels (default 2)
    -c <n>      number of classes (default 3)
    -i <n>      maximum number of iterations (default 4)
    -a:         use apriori probability maps (for initialisation only)
    -A:         use apriori probability maps (for initialisation and for posteriors)
    -ap <prefix> | -Ap <prefix>:        path+filename prefix to pre-registered (to input data) apriori probability maps, 
                   <prefix>_gm _wm and _csf (uncompressed Analyze format)
    -b <v>      MRF neighbourhood beta value (default 0.3)
    -f          disable bias field correction
    -n:         do not output segmentation
    -e:         enable partial volume classification
    --b <v>:    MRF beta value for PVE classification (default 1.5)
    --p:        disable parameter updating during PVE classification
    -od <base>: output basename (default the current)
    -os         output segmentation with one class per image
    -ob         output bias correction field images
    -or         output restored images
    -op         output probability maps (one for each class)
    -ov:        output partial volume images (one for each class)
    -2:         2D segmentation (only for 3D images)
    -v<n>:      verbose level (0-5; default 1)

FMRIB’s Linear Image Registration Tool

http://www.fmrib.ox.ac.uk/fsl/flirt/index.html

command line:

FLIRT version 5.4.2

Usage: /Users/co224/Documents/eclipse-data/workspace/uk.ac.ox.fmrib.fsl.macosx/software//fsl/bin/flirt [options] 
           -in <inputvol> -ref <refvol> -out <outputvol>
       /Users/co224/Documents/eclipse-data/workspace/uk.ac.ox.fmrib.fsl.macosx/software//fsl/bin/flirt [options] 
           -in <inputvol> -ref <refvol> -omat <outputmatrix>
       /Users/co224/Documents/eclipse-data/workspace/uk.ac.ox.fmrib.fsl.macosx/software//fsl/bin/flirt [options] 
           -in <inputvol> -ref <refvol> -applyxfm -init <matrix> -out <outputvol>

  Available options are:
        -in  <inputvol>                    (no default)
        -ref <refvol>                      (no default)
        -init <matrix-filname>             (input 4x4 affine matrix)
        -omat <matrix-filename>            (output in 4x4 ascii format)
        -out, -o <outputvol>               (default is none)
        -datatype {char,short,int,float,double}                    (force output data type)
        -cost {mutualinfo,corratio,normcorr,normmi,leastsq}        (default is corratio)
        -searchcost {mutualinfo,corratio,normcorr,normmi,leastsq}  (default is corratio)
        -anglerep {quaternion,euler}       (default is euler)
        -interp {trilinear,nearestneighbour,sinc}  (final interpolation: def - trilinear)
        -sincwidth <full-width in voxels>  (default is 7)
        -sincwindow {rectangular,hanning,blackman}
        -bins <number of histogram bins>   (default is 256)
        -dof  <number of transform dofs>   (default is 12)
        -noresample                        (do not change input sampling)
        -forcescaling                      (force rescaling even for low-res images)
        -minsampling <vox_dim>             (set minimum voxel dimension for sampling (in mm))
        -applyxfm                          (applies transform (no optimisation) - requires -init)
        -applyisoxfm <scale>               (as applyxfm but forces isotropic resampling)
        -paddingsize <number of voxels>    (for applyxfm: interpolates outside image by size)
        -searchrx <min_angle> <max_angle>  (angles in degrees: default is -90 90)
        -searchry <min_angle> <max_angle>  (angles in degrees: default is -90 90)
        -searchrz <min_angle> <max_angle>  (angles in degrees: default is -90 90)
        -nosearch                          (sets all angular search ranges to 0 0)
        -coarsesearch <delta_angle>        (angle in degrees: default is 60)
        -finesearch <delta_angle>          (angle in degrees: default is 18)
        -schedule <schedule-file>          (replaces default schedule)
        -refweight <volume>                (use weights for reference volume)
        -inweight <volume>                 (use weights for input volume)
        -2D                                (use 2D rigid body mode - ignores dof)
        -verbose <num>                     (0 is least and default)
        -v                                 (same as -verbose 1)
        -i                                 (pauses at each stage: default is off)
        -version                           (prints version number)
        -help

We are mergin the first and second usage scenario. At present, not coding for the third scenario, and not coding for the “Secondary Image” or “low res→hi res→ Reference Image” mode.

FEAT is difficult to recreate in FSLfx. It requires the recreation of design matrix inside FSLfx. Thus, will only be attempted if there is a pressing need.

Multivariate Exploratory Linear Optimized Decomposition into Independent Components

http://www.fmrib.ox.ac.uk/fsl/melodic2/index.html

Command Line:

Usage: 
 melodic -i <filename> <options>
                 to run melodic
 melodic -i <filename> --mix=melodic_mix --filter="string of component numbers"
                 to remove estimated ICs from input
 melodic -i <filename> --ICs=melodic_IC --mix=melodic_mix <options>
                 to run Mixture Model based inference on estimated ICs
 melodic --help 

Compulsory arguments (You MUST set one or more of):
        -i,--in input file name

Optional arguments (You may optionally specify one or more of):
        -o,--outdir     output directory name

        -m,--mask       file name of mask for thresholding
        --nomask        switch off masking
        --nobet         switch off BET
        --bgthreshold   brain / non-brain threshold (only if --nobet selected)

        -d,--dim        dimensionality reduction into #num dimensions (default: automatic estimation)
        --dimest        use specific dim. estimation technique: lap, bic, mdl, aic, mean (default: lap)
        -n,--numICs     numer of IC's to extract (for deflation approach)
        -a,--approach   approach for ICA estimation: defl, symm
        --nl            nonlinearity: gauss, tanh, pow3, pow4
        --vn,--varnorm  switch off variance normalisation
        --covarweight   voxel-wise weights for the covariance matrix (e.g. segmentation information)
        --eps,--epsilon minimum error change
        --maxit         maximum number of iterations before restart
        --maxrestart    maximum number of restarts

        --mmthresh      threshold for Mixture Model based inference
        --no_mm         switch off mixture modelling on IC maps
 
        --ICs           filename of the IC components file for mixture modelling
        --mix           mixing matrix for mixture modelling / filtering
        -f,--filter     component numbers to remove
 
        --report        generate Melodic web report
        --tr            TR in seconds
        --logPower      calculate log of power for frequency spectrum

        --Oall  output everything
        --Ounmix        output unmixing matrix
        --Ostats        output thresholded maps and probability maps
        --Opca          output PCA results
        --Owhite        output whitening/dewhitening matrices
        --Oorig         output the original ICs
        --Omean         output mean volume

        -v,--verbose    switch on diagnostic messages
        -V,--version    prints version information
        --copyright     prints copyright information
        -h,--help       prints this help message

Note: Currently only working for usage 1 scenario above. There are a lot of output, not all coded into the pipeline.

Appears to deal with phase unwrapping. Not sure needed in BMU thus not converted.

Phase Region Expanding Labeller for Unwrapping Discrete Estimates (Prelude) FMRIB’s Utility for Geometrically Unwarping EPIs (FUGUE)

http://www.fmrib.ox.ac.uk/fsl/fugue/index.html

Phase Region Expanding Labeller for Unwrapping Discrete Estimates (Prelude)

Command Line:

prelude (Version 2.0 in c# minor)
Phase Region Expanding Labeller for Unwrapping Discrete Estimates
Copyright(c) 2001, University of Oxford (Mark Jenkinson)

Usage: 
prelude -c <rawphase> -o <unwrappedphase> [options]
prelude -p <phasevol> -a <absvol> -o <unwrappedphase> [options]

Compulsory arguments (You MUST set one or more of):
        -o,--out,-u,--unwrap    filename for saving the unwrapped phase output

Optional arguments (You may optionally specify one or more of):
        -c,--complex    filename of complex phase input volume
        -a,--abs        filename of absolute input volume
        -p,--phase      filename of raw phase input volume
        -n,--numphasesplit      number of phase partitions to use
        --labelslices   does label processing in 2D (slice at a time)
        -s,--slices     does all processing in 2D (slice at a time)
        -f,--force3D    forces all processing to be full 3D
        -t,--thresh     intensity threshold for masking
        -m,--mask       filename of mask input volume
        --start first image number to process (default 0)
        --end   final image number to process (default Inf)
        --savemask      filename for saving the mask volume
        -r,--rawphase   filename for saving the raw phase output
        -l,--labels     filename for saving the area labels output
        --removeramps   remove phase ramps during unwrapping
        -v,--verbose    switch on diagnostic messages
        -h,--help       display this message

FMRIB’s Utility for Geometrically Unwarping EPIs (FUGUE)

Command Line:

fugue (Version 2.2 in c# minor)
FMRIB's Utility for Geometric Unwarping of EPIs
Copyright(c) 2000, University of Oxford (Mark Jenkinson)

Usage: 
fugue -i <epi> -p <unwrapped phase map> -d <dwell-to-asym-ratio> -u <result> [options]
fugue  -i <unwarped-image> -p <unwrapped phase map> -d <dwell-to-asym-ratio> -w <epi-like-result> [options]
fugue -p <unwrapped phase map> -d <dwell-to-asym-ratio> --saveshift=<shiftmap> [options]

Optional arguments (You may optionally specify one or more of):
        -i,--in filename of input volume
        -u,--unwarp     apply unwarping and save as filename
        -w,--warp       apply forward warp and save as filename
        -p,--phasemap   filename for input phase image
        -d,--dwelltoasym        set the dwell to asym time ratio
        --dwell set the EPI dwell time per phase-encode line (sec)
        --asym  set the fieldmap asymmetric spin echo time (sec)
        --savefmap      filename for saving fieldmap (rad/s)
        --loadfmap      filename for loading fieldmap (rad/s)
        --saveshift     filename for saving pixel shift volume
        --loadshift     filename for reading pixel shift volume
        -m,--median     apply 2D median filtering
        --despike       apply a 2D de-spiking filter
        --nofill        do not apply gap-filling measure to the fieldmap
        --noextend      do not apply rigid-body extrapolation to the fieldmap
        --smooth2       apply 2D Gaussian smoothing of sigma N (in mm)
        -s,--smooth3    apply 3D Gaussian smoothing of sigma N (in mm)
        --poly  apply polynomial fitting of order N
        --fourier       apply Fourier (sinusoidal) fitting of order N
        --pava  apply monotonic enforcement via PAVA
        --despikethreshold      specify the threshold for de-spiking (default=3.0)
        --unwarpdir     specifies direction of warping [x/y/z/x-/y-/z-] (default y)
        --phaseconj     apply phase conjugate method of unwarping
        --icorr apply intensity correction to unwarping (pixel shift method only)
        --icorronly     apply intensity correction only (must specify output with -u,--unwarp)
        --mask  filename for loading valid mask
        --unmaskfmap    saves the unmasked fieldmap when using --savefmap
        --unmaskshift   saves the unmasked shiftmap when using --saveshift
        --nokspace      do not use k-space forward warping
        -v,--verbose    switch on diagnostic messages
        -h,--help       display this message



Either --phasemap , --loadshift or --loadfmap MUST be used.

Structural Image Evaluation, using Normalisation, of Atrophy

http://www.fmrib.ox.ac.uk/fsl/siena/index.html

Command Line:

Usage: siena <input1_fileroot> <input2_fileroot> [-d] [-B "bet options"] [-2] [-t2] [-m] [-t <t>] [-b <b>] [-S "siena_diff options"]

-d                    : debug (don't delete intermediate files)
-B "betopts"          : options to pass to BET brain extraction (inside double-quotes), e.g. -B "-f 0.3"
-2                    : two-class segmentation (don't segment grey and white matter separately)
-t2                   : T2-weighted input image (default T1-weighted)
-m                    : use standard-space masking as well as BET
-t <t>                : ignore from t (mm) upwards in MNI152/Talairach space
-b <b>                : ignore from b (mm) downwards in MNI152/Talairach space; b should probably be -ve
-S "sienadiffopts"    : options to pass to siena_diff timepoint differencing (inside double-quotes), e.g. -S "-s -i 20"

Instruction is different from the FEEDS dataset. Usage says I need two compulsory input, but FEEDS says only one.

Not coded into FSLfx.