fsl.wrappers.wrapperutils
¶
This module contains functions and decorators used by the FSL wrapper functions.
The cmdwrapper()
and fslwrapper()
functions are conenience
decorators which allow you to write your wrapper function such that it simply
generates the command-line needed to respectively run a standard shell
command or a FSL command. For example:
@fslwrapper
def fslreorient2std(input, output):
return ['fslreorient2std', input, output]
When this fslreorient2std
function is called, the fslwrapper
decorator
will take care of invoking the command in a standardised way.
The applyArgStyle()
function can be used to automatically convert
keyword arguments into command-line arguments, based on a set of standard
patterns. For example:
@fslwrapper
def flirt(src, ref, **kwargs):
cmd = ['flirt', '-in', src, '-ref', ref]
return cmd + applyArgStyle('-=', **kwargs)
The fileOrImage()
and fileOrArray()
functions can be used to
decorate a wrapper function such that in-memory nibabel
images or Numpy
arrays can be passed in as arguments - they will be automatically saved out to
files, and then the file names passed into the wrapper function. For exmaple:
@fileOrImage('src', 'ref')
@fslwrapper
def flirt(src, ref, **kwargs):
cmd = ['flirt', '-in', src, '-ref', ref]
return cmd + applyArgStyle('-=', **kwargs)
Now this flirt
function can be called either with file names, or
nibabel
images.
Note
Because the fileOrImage()
and fileOrArray()
decorators
manipulate the return value of the decorated function, they should
be applied after any other decorators. Furthermore, if you need to
apply both a fileOrImage
and fileOrArray
decorator to a
function, they should be grouped together, e.g.:
@fileOrImage('a', 'b')
@fileOrArray('c', 'd')
@fslwrapper
def func(**kwargs):
...
Command outputs can also be loaded back into memory by using the special
LOAD
value when calling a wrapper function. For example:
@fileOrImage('src', 'ref', 'out')
@fslwrapper
def flirt(src, ref, **kwargs):
cmd = ['flirt', '-in', src, '-ref', ref]
return cmd + applyArgStyle('-=', **kwargs)
If we set the out
argument to LOAD
, the output image will be loaded
and returned:
src = nib.load('src.nii')
ref = nib.load('ref.nii')
aligned = flirt(src, ref, out=LOAD)['out']
-
fsl.wrappers.wrapperutils.
cmdwrapper
(func)¶ This decorator can be used on functions which generate a command line. It will pass the return value of the function to the
fsl.utils.run.run()
function in a standardised manner.
-
fsl.wrappers.wrapperutils.
fslwrapper
(func)¶ This decorator can be used on functions which generate a FSL command line. It will pass the return value of the function to the
fsl.utils.run.runfsl()
function in a standardised manner.
-
fsl.wrappers.wrapperutils.
SHOW_IF_TRUE
= <object object>¶ Constant to be used in the
valmap
passed to theapplyArgStyle()
function.When a
SHOW_IF_TRUE
argument isTrue
, it is added to the generated command line arguments.
-
fsl.wrappers.wrapperutils.
HIDE_IF_TRUE
= <object object>¶ Constant to be used in the
valmap
passed to theapplyArgStyle()
function.When a
HIDE_IF_TRUE
argument isTrue
, it is suppressed from the generated command line arguments.
-
fsl.wrappers.wrapperutils.
applyArgStyle
(style, valsep=None, argmap=None, valmap=None, **kwargs)¶ Turns the given
kwargs
into command line options. This function is intended to be used to automatically generate command line options from arguments passed into a Python function.The
style
andvalsep
arguments control how key-value pairs are converted into command-line options:style
valsep
Result '-'
‘ ‘ -name val1 val2 val3
'-'
‘”’ -name "val1 val2 val3"
'-'
‘,’ -name val1,val2,val3
'--'
‘ ‘ --name val1 val2 val3
'--'
‘”’ --name "val1 val2 val3"
'--'
‘,’ --name val1,val2,val3
'-='
‘ ‘ Not supported '-='
‘”’ -name="val1 val2 val3"
'-='
‘,’ -name=val1,val2,val3
'--='
‘ ‘ Not supported '--='
‘”’ --name="val1 val2 val3"
'--='
‘,’ --name=val1,val2,val3
Parameters: - style – Controls how the
kwargs
are converted into command-line options - must be one of'-'
,'--'
,'-='
, or'--='
. - valsep – Controls how the values passed to command-line options
which expect multiple arguments are delimited - must be
one of
' '
,','
or'"'
. Defaults to' '
if'=' not in style
,','
otherwise. - argmap – Dictionary of
{kwarg-name : cli-name}
mappings. This can be used if you want to use different argument names in your Python function for the command-line options. - valmap –
Dictionary of
{cli-name : value}
mappings. This can be used to define specific semantics for some command-line options. Acceptable values forvalue
are as followsSHOW_IF_TRUE
- if the argument is present, andTrue
inkwargs
, the command line option will be added (without any arguments).HIDE_IF_TRUE
- if the argument is present, andFalse
inkwargs
, the command line option will be added (without any arguments).- Any other constant value. If the argument is present
in
kwargs
, its command-line option will be added, with the constant value as its argument.
The argument for any options not specified in the
valmap
will be converted into strings. - kwargs – Arguments to be converted into command-line options.
Returns: A list containing the generated command-line options.
- style – Controls how the
-
fsl.wrappers.wrapperutils.
namedPositionals
(func, args)¶ Given a function, and a sequence of positional arguments destined for that function, identifies the name for each positional argument. Variable positional arguments are given an automatic name.
Parameters: - func – Function which will accept
args
as positionals. - args – Tuple of positional arguments to be passed to
func
.
- func – Function which will accept
-
fsl.wrappers.wrapperutils.
LOAD
= <object object>¶ Constant used by the
_FileOrThing
class to indicate that an output file should be loaded into memory and returned as a Python object.
-
fsl.wrappers.wrapperutils.
fileOrImage
(*args, **kwargs)¶ Decorator which can be used to ensure that any NIfTI images are saved to file, and output images can be loaded and returned as
nibabel
image objects orImage
objects.
-
fsl.wrappers.wrapperutils.
fileOrArray
(*args, **kwargs)¶ Decorator which can be used to ensure that any Numpy arrays are saved to text files, and output files can be loaded and returned as Numpy arrays.