fsl.wrappers.wrapperutils
¶
This module contains functions and decorators used by the FSL wrapper functions.
The cmdwrapper()
and fslwrapper()
functions are convenience
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 example:
@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.
_update_wrapper
(wrapper, wrapped, *args, **kwargs)[source]¶ Replacement for the built-in
functools.update_wrapper
. This implementation ensures that the wrapper function has an attribute called__wrapped__
, which refers to thewrapped
function.This custom function is only needed in Python versions < 3.4.
-
fsl.wrappers.wrapperutils.
_unwrap
(func)[source]¶ Replacement for the built-in
inspect.unwrap
function, which is not present in Python versions prior to 3.4.
-
fsl.wrappers.wrapperutils.
cmdwrapper
(func)[source]¶ 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)[source]¶ 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, singlechar_args=False, **kwargs)[source]¶ 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.singlechar_args – If True, single character arguments always take a single hyphen prefix (e.g. -h) regardless of the style.
kwargs – Arguments to be converted into command-line options.
- Returns
A list containing the generated command-line options.
-
fsl.wrappers.wrapperutils.
namedPositionals
(func, args)[source]¶ 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
.
-
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.
-
class
fsl.wrappers.wrapperutils.
FileOrThing
(func, prepIn, prepOut, load, removeExt, *args, **kwargs)[source]¶ Bases:
object
Decorator which ensures that certain arguments which are passed into the decorated function are always passed as file names. Both positional and keyword arguments can be specified.
The
FileOrThing
class is not intended to be used directly - see thefileOrImage()
andfileOrArray()
decorator functions for more details.These decorators are intended for functions which wrap a command-line tool, i.e. where some inputs/outputs need to be specified as file names.
Inputs
Any arguments which are not of type
Thing
are passed through to the decorated function unmodified. Arguments which are of typeThing
are saved to a temporary file, and the name of that file is passed to the function.Outputs
If an argument is given the special
LOAD
value, it is assumed to be an output argument. In this case, it is replaced with a temporary file name then, after the function has completed, that file is loaded into memory, and the value returned (along with the function’s output, and any other arguments with a value ofLOAD
).Return value
Functions decorated with a
FileOrThing
decorator will always return adict
-like object, where the function’s actual return value is accessible via an attribute calledstdout
. All output arguments with a value ofLOAD
will be present as dictionary entries, with the keyword argument names used as keys; these values will also be accessible as attributes of the results dict, when possible. AnyLOAD
output arguments which were not generated by the function will not be present in the dictionary.Cluster submission
The above description holds in all situations, except when an argument called
submit
is passed, and is set to a value which evaluates toTrue
. In this case, theFileOrThing
decorator will pass all arguments straight through to the decorated function, and will return its return value unchanged.This is because most functions that are decorated with the
fileOrImage()
orfileOrArray()
decorators will invoke a call torun.run()
orrunfsl()
, where a value ofsubmit=True
will cause the command to be executed asynchronously on a cluster platform.A
ValueError
will be raised if the decorated function is called withsubmit=True
, and with any in-memory objects orLOAD
symbols.Example
As an example of using the
fileOrArray
decorator on a function which concatenates two files containing affine transformations, and saves the output to a file:# if atob, btoc, or output are passed # in as arrays, they are converted to # file names. @fileOrArray('atob', 'btoc', 'output') def concat(atob, btoc, output=None): # inputs are guaranteed to be files atob = np.loadtxt(atob) btoc = np.loadtxt(atoc) atoc = np.dot(btoc, atob) if output is not None: np.savetxt(output, atoc) return 'Done'
Because we have decorated the
concat
function withfileToArray()
, it can be called with either file names, or Numpy arrays:# All arguments are passed through # unmodified - the output will be # saved to a file called atoc.mat. concat('atob.txt', 'btoc.txt', 'atoc.mat') # The function's return value # is accessed via an attribute called # "stdout" on the dict assert concat('atob.txt', 'btoc.txt', 'atoc.mat').stdout == 'Done' # Outputs to be loaded into memory # are returned in a dictionary, # with argument names as keys. Values # can be accessed as dict items, or # as attributes. atoc = concat('atob.txt', 'btoc.txt', LOAD)['atoc'] atoc = concat('atob.txt', 'btoc.txt', LOAD).atoc # In-memory inputs are saved to # temporary files, and those file # names are passed to the concat # function. atoc = concat(np.diag([2, 2, 2, 0]), np.diag([3, 3, 3, 3]), LOAD).atoc
Using with other decorators
FileOrThing
decorators can be chained with otherFileOrThing
decorators, and other decorators. When multipleFileOrThing
decorators are used on a single function, the outputs from each decorator are merged together into a single dict-like object.FileOrThing
decorators can be used with any other decorators as long as they do not manipulate the return value, and as long as theFileOrThing
decorators are adjacent to each other.-
class
Results
(stdout)[source]¶ Bases:
dict
A custom
dict
type used to return outputs from a function decorated withFileOrThing
. All outputs are stored as dictionary items, with the argument name as key, and the output object (the “thing”) as value.Where possible (i.e. for outputs named with a valid Python identifier), the outputs are also made accessible as attributes of the
Results
object.The decorated function’s actual return value is accessible via the
stdout()
property.-
__init__
(stdout)[source]¶ Create a
Results
dict.- Parameters
stdout – Return value of the decorated function (typically a tuple containing the standard output and error of the underlying command).
-
property
stdout
¶ Access the return value of the decorated function.
-
__dict__
= mappingproxy({'__module__': 'fsl.wrappers.wrapperutils', '__doc__': 'A custom ``dict`` type used to return outputs from a function\n decorated with ``FileOrThing``. All outputs are stored as dictionary\n items, with the argument name as key, and the output object (the\n "thing") as value.\n\n Where possible (i.e. for outputs named with a valid Python\n identifier), the outputs are also made accessible as attributes of\n the ``Results`` object.\n\n The decorated function\'s actual return value is accessible via the\n :meth:`stdout` property.\n ', '__init__': <function FileOrThing.Results.__init__>, '__setitem__': <function FileOrThing.Results.__setitem__>, 'stdout': <property object>, '__dict__': <attribute '__dict__' of 'Results' objects>, '__weakref__': <attribute '__weakref__' of 'Results' objects>})¶
-
__module__
= 'fsl.wrappers.wrapperutils'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
__init__
(func, prepIn, prepOut, load, removeExt, *args, **kwargs)[source]¶ Initialise a
FileOrThing
decorator.- Parameters
func – The function to be decorated.
prepIn – Function which returns a file name to be used in place of an input argument.
prepOut – Function which generates a file name to use for arguments that were set to
LOAD
.load –
Function which is called to load items for arguments that were set to
LOAD
. Must accept the following arguments:the name of the argument
path to the file to be loaded
removeExt – Function which can remove a file extension from a file path.
outprefix – Must be passed as a keyword argument. The name of a positional or keyword argument to the function, which specifies an output file name prefix. All other arguments with names that begin with this prefix may be interpreted as things to
LOAD
.
All other positional arguments are interpreted as the names of the arguments to the function which will be handled by this
FileOrThing
decorator. If not provided, all arguments passed to the function will be handled.The
prepIn
andprepOut
functions must accept the following positional arguments:A directory in which all temporary input/output files should be stored
The name of the keyword argument to be processed
The argument value that was passed in
-
__call__
(*args, **kwargs)[source]¶ Function which calls
func
, ensuring that any arguments of typeThing
are saved to temporary files, and any arguments with the valueLOAD
are loaded and returned.All other arguments are passed through to
func
.
-
_FileOrThing__generateResult
(workdir, result, outprefix, outfiles, prefixes)¶ Loads function outputs and returns a
Results
object.Called by
__call__()
after the decorated function has been called. Figures out what files should be loaded, and loads them into aResults
object.- Parameters
workdir – Directory which contains the function outputs.
result – Function return value.
outprefix – Original output prefix that was passed into the function (or
None
if one wasn’t passed)outfiles – Dictionary containing output files to be loaded (see
__prepareArgs()
).prefixes – Dictionary containing output-prefix patterns to be loaded (see
__prepareArgs()
).
- Returns
A
Results
object containing all loaded outputs.
-
_FileOrThing__prepareArgs
(parent, workdir, argnames, args, kwargs)¶ Prepares all input and output arguments to be passed to the decorated function. Any arguments with a value of
LOAD
are passed to theprepOut
function specified at__init__()
. All other arguments are passed through theprepIn
function.- Parameters
parent –
True
if thisFileOrThing
is the first in a chain ofFileOrThing
decorators.workdir – Directory in which all temporary files should be stored.
args – Positional arguments to be passed to the decorated function.
kwargs – Keyword arguments to be passed to the decorated function.
- Returns
A tuple containing:
An updated copy of
args
.An updated copy of
kwargs
.The output file prefix that was actually passed in (it is subsequently modified so that prefixed outputs are redirected to a temporary location). All prefixed outputs that are not
LOAD``ed should be moved into this directory. ``None
if there is no output prefix.A dictionary of
{ name : filename }
mappings, for all arguments with a value ofLOAD
.A dictionary of
{ filepat : replstr }
paths, for all output-prefix arguments with a value ofLOAD
.
-
__dict__
= mappingproxy({'__module__': 'fsl.wrappers.wrapperutils', '__doc__': 'Decorator which ensures that certain arguments which are passed into the\n decorated function are always passed as file names. Both positional and\n keyword arguments can be specified.\n\n\n The ``FileOrThing`` class is not intended to be used directly - see the\n :func:`fileOrImage` and :func:`fileOrArray` decorator functions for more\n details.\n\n\n These decorators are intended for functions which wrap a command-line tool,\n i.e. where some inputs/outputs need to be specified as file names.\n\n\n **Inputs**\n\n\n Any arguments which are not of type ``Thing`` are passed through to the\n decorated function unmodified. Arguments which are of type ``Thing`` are\n saved to a temporary file, and the name of that file is passed to the\n function.\n\n\n **Outputs**\n\n\n If an argument is given the special :data:`LOAD` value, it is assumed\n to be an output argument. In this case, it is replaced with a temporary\n file name then, after the function has completed, that file is loaded\n into memory, and the value returned (along with the function\'s output,\n and any other arguments with a value of ``LOAD``).\n\n\n **Return value**\n\n\n Functions decorated with a ``FileOrThing`` decorator will always return a\n ``dict``-like object, where the function\'s actual return value is\n accessible via an attribute called ``stdout``. All output arguments with a\n value of ``LOAD`` will be present as dictionary entries, with the keyword\n argument names used as keys; these values will also be accessible as\n attributes of the results dict, when possible. Any ``LOAD`` output\n arguments which were not generated by the function will not be present in\n the dictionary.\n\n\n **Cluster submission**\n\n\n The above description holds in all situations, except when an argument\n called ``submit`` is passed, and is set to a value which evaluates to\n ``True``. In this case, the ``FileOrThing`` decorator will pass all\n arguments straight through to the decorated function, and will return its\n return value unchanged.\n\n\n This is because most functions that are decorated with the\n :func:`fileOrImage` or :func:`fileOrArray` decorators will invoke a call\n to :func:`.run.run` or :func:`.runfsl`, where a value of ``submit=True``\n will cause the command to be executed asynchronously on a cluster\n platform.\n\n\n A :exc:`ValueError` will be raised if the decorated function is called\n with ``submit=True``, and with any in-memory objects or ``LOAD`` symbols.\n\n\n **Example**\n\n\n As an example of using the ``fileOrArray`` decorator on a function\n which concatenates two files containing affine transformations, and\n saves the output to a file::\n\n # if atob, btoc, or output are passed\n # in as arrays, they are converted to\n # file names.\n @fileOrArray(\'atob\', \'btoc\', \'output\')\n def concat(atob, btoc, output=None):\n\n # inputs are guaranteed to be files\n atob = np.loadtxt(atob)\n btoc = np.loadtxt(atoc)\n\n atoc = np.dot(btoc, atob)\n\n if output is not None:\n np.savetxt(output, atoc)\n\n return \'Done\'\n\n\n Because we have decorated the ``concat`` function with :func:`fileToArray`,\n it can be called with either file names, or Numpy arrays::\n\n\n # All arguments are passed through\n # unmodified - the output will be\n # saved to a file called atoc.mat.\n concat(\'atob.txt\', \'btoc.txt\', \'atoc.mat\')\n\n # The function\'s return value\n # is accessed via an attribute called\n # "stdout" on the dict\n assert concat(\'atob.txt\', \'btoc.txt\', \'atoc.mat\').stdout == \'Done\'\n\n # Outputs to be loaded into memory\n # are returned in a dictionary,\n # with argument names as keys. Values\n # can be accessed as dict items, or\n # as attributes.\n atoc = concat(\'atob.txt\', \'btoc.txt\', LOAD)[\'atoc\']\n atoc = concat(\'atob.txt\', \'btoc.txt\', LOAD).atoc\n\n # In-memory inputs are saved to\n # temporary files, and those file\n # names are passed to the concat\n # function.\n atoc = concat(np.diag([2, 2, 2, 0]),\n np.diag([3, 3, 3, 3]), LOAD).atoc\n\n\n **Using with other decorators**\n\n\n ``FileOrThing`` decorators can be chained with other ``FileOrThing``\n decorators, and other decorators. When multiple ``FileOrThing``\n decorators are used on a single function, the outputs from each decorator\n are merged together into a single dict-like object.\n\n\n ``FileOrThing`` decorators can be used with any other decorators\n **as long as** they do not manipulate the return value, and as long as\n the ``FileOrThing`` decorators are adjacent to each other.\n ', 'Results': <class 'fsl.wrappers.wrapperutils.FileOrThing.Results'>, '__init__': <function FileOrThing.__init__>, '__call__': <function FileOrThing.__call__>, '_FileOrThing__prepareArgs': <function FileOrThing.__prepareArgs>, '_FileOrThing__generateResult': <function FileOrThing.__generateResult>, '__dict__': <attribute '__dict__' of 'FileOrThing' objects>, '__weakref__': <attribute '__weakref__' of 'FileOrThing' objects>})¶
-
__module__
= 'fsl.wrappers.wrapperutils'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
class
-
fsl.wrappers.wrapperutils.
fileOrImage
(*args, **kwargs)[source]¶ 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)[source]¶ 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.
-
fsl.wrappers.wrapperutils.
fileOrText
(*args, **kwargs)[source]¶ Decorator which can be used to ensure that any text output (e.g. log file) are saved to text files, and output files can be loaded and returned as strings.
To be able to distinguish between input values and input file paths, the
fileOrText
decorator requires that input and output file paths are passed in aspathlib.Path
objects. For example, given a function like this:@fileOrText() def myfunc(infile, outfile): ...
if we want to pass file paths for both
infile
andoutfile
, we would do this:from pathlib import Path myfunc(Path('input.txt'), Path('output.txt'))
Input values may be passed in as normal strings, e.g.:
myfunc('input data', Path('output.txt'))
Output values can be loaded as normal via the
LOAD
symbol, e.g.:myfunc(Path('input.txt'), LOAD)