fslx

fslx is a simple wrapper around some of FSL tools. It exists so that users don’t have to remember the arbitrary names of FSL tools, nor the parameter naming conventions of each of them.

Syntax

The usage syntax is the same for all operations: fslx op img1

Or, if you want to process multiple files simultaneously: fslx op img1 img2 img3 ...

Exceptions to the rule are simple to remember though, such as in the case of realignment:

fslx reg reference img1 img2 img3

Another exception is merging files, where fslx does what the user would expect - it merges all inputs.

fslx merge img1 img2 img3

To make things as simple and intuitive as possible, operations have alias so that synonyms can be used and things just work. Alignment, for example, can be called with any of reg|align|register.

Supported operations

As of yet, FSLX supports the following:

Operation	Effect	Pipeable	Original FSL operations
tmean	Compute temporal mean	yes	fslmaths -Tmean
simplemean	Compute mean over all voxels	no	python + nibabel
simplestd	Compute std over all voxels	no	python + nibabel
tstd	Compute temporal std	yes	fslmaths -Tstd
tsnr	Compute temporal tsnr	yes	fslmaths mean -div std
tsnrtr or trtsnr	Compute temporal tsnr / sqrt(TR)	yes	fslmaths mean -div std
moco or mc	Motion correction	yes	mcflirt
mocome	Motion correction for multiechoes	yes	mcflirt
ica or melodic	ICA of all inputs. Pipes IC maps	yes	melodic -i
view or v	Open files in viewer, pipes through	yes	fslview
brain or rmskull or bet	Remove skull	yes	bet
merge or tmerge	Merge 2D -> or 3D -> 4D	yes	fslmerge
echocombine of mecombine	Merge echoes by averaging	yes	fslmaths -add & -div
split or tsplit	Split 4D image into multiple 3D	not yet	fslsplit
align or register or reg	Align image to reference	yes	flirt
lthresh or lthr <THRESH>	Low threshold, usage: fslx lthr 10	yes	fslmaths -thr
uthresh or uthr <THRESH>	Upper threshold, usage: fslx uthr 5	yes	fslmaths -uthr
gauss or sm <KSIZE_MM>	Gauss filter(mm), usage: fslx sm 5	yes	fslmaths -s
susan or smooth <KSIZE_MM>	Smooth image(mm), usage: fslx sm 5	yes	susan
highpass or hpass	Hpass filter(s), usage: fslx hpass 5	yes	fslmaths -bptf N -1
nan or nans	image(image==nan) = 0	yes	fslmaths -nan
exp	Compute e^image	yes	fslmaths -exp
sin	Compute sin(image)	yes	fslmaths -sin
abs or mag or magn	Compute abs(image)	yes	fslmaths -abs
bin	image(image>0) ? 1 : 0	yes	fslmaths -bin
recip	1/image, voxelwise	yes	fslmaths -recip
header or hd	Read image header	no	fslhd
nvols	Query number of volumes in image	no	fslnvols
cc or crosscorr	Compute cross correlation	no	fslcc
cluster <THRESH>	Compute clusters above threshold	no	cluster
fdr	False Discovery Rate Correction	yes	melodic
info	Query info, e.g., image dimensions	no	fslinfo
tr or TR	Query the TR	no	fslinfo
mm or mixturemodel	Mixture modelling of IC components	yes	melodic

Coming soon, hopefully: stats, segmentation with FAST, smart registration to MNI152.

Notes: output ICs from Melodic will be copied to local folder to be consistent with fslx conventions. Moreover, the Melodic output folder will be renamed but the contents will not be changed. I consider this to be a good middle ground between usability and compatibility with other tools that expect a Melodic directory as input, such as ICA-AROMA.

Notes2: Motion correction for multiple echoes applies the transforms obtained by motion correcting the first echo on all subsequent echoes.

Notes3: Highpass and lowpass filters accept a cutoff parameter in SECONDS. The conversion to volumes is done inside of fslx. Filters also add the mean back, so the user doesn’t have to do it. I feel that is a better default for most use cases.

Piping commands

You can use xargs to build processing pipelines. Most operations are supported. Example - motion correct, compute the tSNR, remove NaNs of all 4D niftis in a directory (and register then to a T1 weighted, of course):

ls | xargs flsx moco | xargs fslx tsnr | xargs fslx nan | xargs fslx reg T1w

To maximize simplicity, you can alias xargs fslx:

alias xfslx='xargs fslx '
ls | xflsx moco | xfslx tsnr | xfslx nan | xfslx reg T1w > list_of_processed_files.txt

And then call the pipe with less verbosity.

To see intermediate results, simply add a call to the viewer in the middle of your pipe:

alias xfslx='xargs fslx '
ls | xfslx moco | xfslx tsnr | xfslx nan | xfslx v |xfslx reg T1w > list_of_processed_files.txt

Note: you get all of your intermediate results, so make sure you have enough disk space. If you don’t want to store intermediate results, you can probably write a list of intermediates to a file (using, e.g., tee) and rm then when all processing is done successfully, example:

ls | xfslx moco | tee mocoed.txt | xfslx tsnr >/dev/null; cat mocoed.txt | xargs rm

Note2: fslx doesn’t allow configuring output directories yet. Therefore, as a workaround you can use xargs and mv to output files to wherever you want:

ls | xfslx moco | tee mocoed.txt | xfslx tnsr | tee tsnred.txt
xargs -a mocoed.txt mv -t /path/where/mocoed/files/should/go
xargs -a tsnred.txt mv -t /path/where/tsnred/files/should/go

Installation

Put fslx on your PATH.

git clone https://github.com/dangom/fslx.git
chmod +x fslx/fslx
currdir=`pwd`
echo 'export "PATH='$currdir'/fslx/:$PATH"' >> ~/.bashrc

Dependencies

• FSL
• A Unix like environment with a shell available.
• GNU Readlink (for macOS: brew install coreutils). Will remove dependency eventually.
• For the simplemean and simplestd operations, python + nibabel are necessary.

TO DO

• [x] PRIORITY: Support relative filenames.
• [ ] Support for applyxfm, registration to MNI, concatenate transformation matrices.
• [ ]FAST segmentation
• [ ] Add support for dual_regression and randomize
• [x] Add support for mixture modelling.

Why?

• Other pipelines are too verbose and do not allow for quick data exploration.
• Its common to forget FSL naming conventions, and the Wiki isn’t always clear.
• FSL has decent defaults and 95% of the times there is no need to customize anything.

Acknowledgements

The awesome FSL. The poweful BASH.

Disclaimer

This tool is not a part of FSL. Use at your own risk.

THE PROGRAM IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL, BUT WITHOUT ANY WARRANTY. IT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW THE AUTHOR WILL BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.