wrapperutils.py 30.1 KB
Newer Older
1
2
#!/usr/bin/env python
#
Paul McCarthy's avatar
Paul McCarthy committed
3
4
# wrapperutils.py - Functions and decorators used by the FSL wrapper
# functions.
5
6
7
#
# Author: Paul McCarthy <pauldmccarthy@gmail.com>
#
Paul McCarthy's avatar
Paul McCarthy committed
8
9
10
11
"""This module contains functions and decorators used by the FSL wrapper
functions.


12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
The :func:`cmdwrapper` and :func:`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.


Paul McCarthy's avatar
Paul McCarthy committed
27
The :func:`applyArgStyle` function can be used to automatically convert
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
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 :func:`fileOrImage` and :func:`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.


55
56
57
58
59
60
61
.. note:: Because the :func:`fileOrImage` and :func:`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')
Paul McCarthy's avatar
Paul McCarthy committed
62
              @fileOrArray('c', 'd')
63
64
65
66
67
              @fslwrapper
              def func(**kwargs):
                  ...


68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
Command outputs can also be loaded back into memory by using the special
:data:`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']
Paul McCarthy's avatar
Paul McCarthy committed
85
"""
86
87
88
89


import os.path as op
import            os
Paul McCarthy's avatar
Paul McCarthy committed
90
import            sys
91
92
import            glob
import            shutil
93
94
import            random
import            string
95
import            fnmatch
96
import            inspect
97
import            logging
98
99
100
101
102
103
104
import            tempfile
import            warnings
import            functools
import            collections

import            six
import nibabel as nib
Paul McCarthy's avatar
Paul McCarthy committed
105
import numpy   as np
106

107
import fsl.utils.run     as run
108
109
import fsl.utils.path    as fslpath
import fsl.utils.tempdir as tempdir
110
111
112
import fsl.data.image    as fslimage


113
114
115
log = logging.getLogger(__name__)


Paul McCarthy's avatar
Paul McCarthy committed
116
117
118
119
120
def _update_wrapper(wrapper, wrapped, *args, **kwargs):
    """Replacement for the built-in ``functools.update_wrapper``. This
    implementation ensures that the wrapper function has an attribute
    called ``__wrapped__``, which refers to the ``wrapped`` function.

121
    This custom function is only needed in Python versions < 3.4.
Paul McCarthy's avatar
Paul McCarthy committed
122
123
124
125
126
    """

    wrapper = functools.update_wrapper(wrapper, wrapped, *args, **kwargs)

    # Python >= 3.4 does things right
Paul McCarthy's avatar
Paul McCarthy committed
127
    if (sys.version_info[0] * 10 + sys.version_info[1]) < 34:
Paul McCarthy's avatar
Paul McCarthy committed
128
129
        wrapper.__wrapped__ = wrapped
    return wrapper
130
131


Paul McCarthy's avatar
Paul McCarthy committed
132
133
134
135
136
137
def _unwrap(func):
    """Replacement for the built-in ``inspect.unwrap`` function, which
    is not present in Python versions prior to 3.4.
    """

    # Python >= 3.4 has an inspect.unwrap function
Paul McCarthy's avatar
Paul McCarthy committed
138
    if (sys.version_info[0] * 10 + sys.version_info[1]) >= 34:
Paul McCarthy's avatar
Paul McCarthy committed
139
140
141
142
143
144
145
146
147
        return inspect.unwrap(func)

    # Otherwise we follow the __wrapped__ chain ourselves
    if hasattr(func, '__wrapped__'):
        return _unwrap(func.__wrapped__)

    return func


148
149
150
151
152
153
def 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
    :func:`fsl.utils.run.run` function in a standardised manner.
    """
    def wrapper(*args, **kwargs):
154
        submit = kwargs.pop('submit', None)
155
156
157
158
        stderr = kwargs.pop('stderr', True)
        log    = kwargs.pop('log',    {'tee' : True})
        cmd    = func(*args, **kwargs)
        return run.run(cmd, stderr=stderr, log=log, submit=submit)
159
160
161
162
163
164
165
166
167
    return _update_wrapper(wrapper, func)


def 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
    :func:`fsl.utils.run.runfsl` function in a standardised manner.
    """
    def wrapper(*args, **kwargs):
168
        submit = kwargs.pop('submit', None)
169
170
171
172
        stderr = kwargs.pop('stderr', True)
        log    = kwargs.pop('log',    {'tee' : True})
        cmd    = func(*args, **kwargs)
        return run.runfsl(cmd, stderr=stderr, log=log, submit=submit)
173
174
175
    return _update_wrapper(wrapper, func)


Paul McCarthy's avatar
Paul McCarthy committed
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
SHOW_IF_TRUE = object()
"""Constant to be used in the ``valmap`` passed to the :func:`applyArgStyle`
function.

When a ``SHOW_IF_TRUE`` argument is ``True``, it is added to the generated
command line arguments.
"""


HIDE_IF_TRUE = object()
"""Constant to be used in the ``valmap`` passed to the :func:`applyArgStyle`
function.

When a ``HIDE_IF_TRUE`` argument is ``True``, it is suppressed from the
generated command line arguments.
"""
192
193


194
def applyArgStyle(style, valsep=None, argmap=None, valmap=None, **kwargs):
Paul McCarthy's avatar
Paul McCarthy committed
195
196
197
198
    """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.

199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
    The ``style`` and ``valsep`` 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``
    =========  ==========  ===========================


Paul McCarthy's avatar
Paul McCarthy committed
221
    :arg style:  Controls how the ``kwargs`` are converted into command-line
222
223
224
225
226
                 options - must be one of ``'-'``, ``'--'``, ``'-='``, or
                 ``'--='``.

    :arg valsep: Controls how the values passed to command-line options
                 which expect multiple arguments are delimited - must be
227
228
                 one of ``' '``, ``','`` or ``'"'``. Defaults to ``' '``
                 if ``'=' not in style``, ``','`` otherwise.
Paul McCarthy's avatar
Paul McCarthy committed
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251

    :arg 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.

    :arg valmap: Dictionary of ``{cli-name : value}`` mappings. This can be
                 used to define specific semantics for some command-line
                 options. Acceptable values for ``value`` are as follows

                  - :data:`SHOW_IF_TRUE` - if the argument is present, and
                    ``True`` in ``kwargs``, the command line option
                    will be added (without any arguments).

                  - :data:`HIDE_IF_TRUE` - if the argument is present, and
                    ``False`` in ``kwargs``, 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.
252

Paul McCarthy's avatar
Paul McCarthy committed
253
254
255
256
257
    :arg kwargs: Arguments to be converted into command-line options.

    :returns:    A list containing the generated command-line options.
    """

258
259
260
261
    if valsep is None:
        if '=' in style: valsep = ','
        else:            valsep = ' '

Paul McCarthy's avatar
Paul McCarthy committed
262
263
    if style not in ('-', '--', '-=', '--='):
        raise ValueError('Invalid style: {}'.format(style))
264
265
266
267
268
269
270
271
272
    if valsep not in (' ', ',', '"'):
        raise ValueError('Invalid valsep: {}'.format(valsep))

    # we don't handle the case where '=' in
    # style, and valsep == ' ', because no
    # sane CLI app would do this. Right?
    if '=' in style and valsep == ' ':
        raise ValueError('Incompatible style and valsep: s={} v={}'.format(
            style, valsep))
Paul McCarthy's avatar
Paul McCarthy committed
273
274
275
276
277

    if argmap is None: argmap = {}
    if valmap is None: valmap = {}

    def fmtarg(arg):
278
279
280
281
        if   style in ('-',  '-='):  arg =  '-{}'.format(arg)
        elif style in ('--', '--='): arg = '--{}'.format(arg)
        return arg

282
    # always returns a sequence
Paul McCarthy's avatar
Paul McCarthy committed
283
    def fmtval(val):
284
285
        if     isinstance(val, collections.Sequence) and \
           not isinstance(val, six.string_types):
286
287
288
289
290

            val = [str(v) for v in val]
            if   valsep == ' ': return val
            elif valsep == '"': return [' '   .join(val)]
            else:               return [valsep.join(val)]
291
        else:
292
293
294
295
296
297
298
299
            return [str(val)]

    # val is assumed to be a sequence
    def fmtargval(arg, val):
        # if '=' in style, val will
        # always be a single string
        if '=' in style: return ['{}={}'.format(arg, val[0])]
        else:            return [arg] + val
300
301
302
303
304
305

    args = []

    for k, v in kwargs.items():

        k    = argmap.get(k, k)
Paul McCarthy's avatar
Paul McCarthy committed
306
307
308
        mapv = valmap.get(k, fmtval(v))
        k    = fmtarg(k)

309

310
311
312
313
        if mapv in (SHOW_IF_TRUE, HIDE_IF_TRUE):
            if (mapv is SHOW_IF_TRUE and     v) or \
               (mapv is HIDE_IF_TRUE and not v):
                args.append(k)
314
        else:
315
            args.extend(fmtargval(k, mapv))
316
317
318
319

    return args


320
def namedPositionals(func, args):
321
    """Given a function, and a sequence of positional arguments destined
322
    for that function, identifies the name for each positional argument.
323
    Variable positional arguments are given an automatic name.
324

325
326
    :arg func: Function which will accept ``args`` as positionals.
    :arg args: Tuple of positional arguments to be passed to ``func``.
327
    """
Paul McCarthy's avatar
Paul McCarthy committed
328

329
330
331
332
333
334
335
336
337
338
    # Current implementation will
    # result in naming collisions
    # for something like this:
    #
    # def func(args0, *args):
    #     ...
    # because of automatic vararg
    # naming. But who would write
    # a function like that anyway?

339
340
    # Remove any decorators
    # from the function
Paul McCarthy's avatar
Paul McCarthy committed
341
342
    func = _unwrap(func)

343
344
345
    # getargspec is the only way to
    # get the names of positional
    # arguments in Python 2.x.
Paul McCarthy's avatar
Paul McCarthy committed
346
    if sys.version_info[0] < 3:
347
348
349
        spec     = inspect.getargspec(func)
        argnames = spec.args
        varargs  = spec.varargs
Paul McCarthy's avatar
Paul McCarthy committed
350

351
352
    # But getargspec is deprecated
    # in python 3.x
Paul McCarthy's avatar
Paul McCarthy committed
353
354
355
356
357
358
    else:

        # getfullargspec is deprecated in
        # python 3.5, but not in python 3.6.
        with warnings.catch_warnings():
            warnings.filterwarnings('ignore', category=DeprecationWarning)
359
360
361
            spec     = inspect.getfullargspec(func)
            argnames = spec.args
            varargs  = spec.varargs
362

363
364
365
    # we only care about the arguments
    # that are being passed in
    argnames = argnames[:len(args)]
366

367
368
369
370
    # make up names for varargs
    nvarargs = len(args) - len(argnames)
    if varargs is not None and nvarargs > 0:
        argnames += ['{}{}'.format(varargs, i) for i in range(nvarargs)]
371

372
    return argnames
373
374


Paul McCarthy's avatar
Paul McCarthy committed
375
LOAD = object()
Paul McCarthy's avatar
Paul McCarthy committed
376
377
"""Constant used by the :class:`_FileOrThing` class to indicate that an output
file should be loaded into memory and returned as a Python object.
378
379
380
"""


Paul McCarthy's avatar
Paul McCarthy committed
381
382
383
384
385
386
387
388
389
390
class _FileOrThing(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 the
    :func:`fileOrImage` and :func:`fileOrArray` decorator functions for more
    details.

391

Paul McCarthy's avatar
Paul McCarthy committed
392
393
394
395
396
397
398
399
400
401
402
403
    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 type ``Thing`` are
    saved to a temporary file, and the name of that file is passed to the
    function.

404

Paul McCarthy's avatar
Paul McCarthy committed
405
    **Outputs**
406
407


Paul McCarthy's avatar
Paul McCarthy committed
408
    If an argument is given the special :data:`LOAD` value, it is assumed
Paul McCarthy's avatar
Paul McCarthy committed
409
410
411
    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,
Paul McCarthy's avatar
Paul McCarthy committed
412
    and any other arguments with a value of ``LOAD``).
Paul McCarthy's avatar
Paul McCarthy committed
413
414
415
416
417
418


    **Return value**


    Functions decorated with a ``_FileOrThing`` decorator will always return a
419
420
421
422
423
    ``dict``-like object, where the function's actual return value is
    accessible via an attribute called `output`. All output arguments with a
    value of ``LOAD`` will be present as dictionary entries, with the keyword
    argument names used as keys. Any ``LOAD``ed output arguments which were not
    generated by the function will not be present in the dictionary.
Paul McCarthy's avatar
Paul McCarthy committed
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447


    **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)

448
449
            return 'Done'

Paul McCarthy's avatar
Paul McCarthy committed
450
451
452
453

    Because we have decorated the ``concat`` function with :func:`fileToArray`,
    it can be called with either file names, or Numpy arrays::

454

Paul McCarthy's avatar
Paul McCarthy committed
455
456
        # All arguments are passed through
        # unmodified - the output will be
457
        # saved to a file called atoc.mat.
Paul McCarthy's avatar
Paul McCarthy committed
458
459
        concat('atob.txt', 'btoc.txt', 'atoc.mat')

460
461
462
463
464
465
466
467
468
        # The function's return value
        # is accessed via an attribute called
        # "output" on the dict
        assert concat('atob.txt', 'btoc.txt', 'atoc.mat').output == 'Done'

        # Outputs to be loaded into memory
        # are returned in a dictionary,
        # with argument names as keys.
        atoc = concat('atob.txt', 'btoc.txt', LOAD)['atoc']
Paul McCarthy's avatar
Paul McCarthy committed
469

470
471
472
473
474
475
476
477
478
        # 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**
Paul McCarthy's avatar
Paul McCarthy committed
479
480
481
482
483
484
485
486
487


    ``_FileOrThing`` decorators can be chained with other ``_FileOrThing``
    decorators, and other decorators.  When multiple ``_FileOrThing``
    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
488
    **as long as** they do not manipulate the return value.
489
490
491
    """


492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
    class _Results(dict):
        """A custom ``dict`` type used to return outputs from a function
        decorated with ``_FileOrThing``. All outputs are stored as dictionary
        items, with the argument name as key, and the output object (the
        "thing") as value.

        The decorated function's actual return value is accessible via the
        :meth:`output` property.
        """
        def __init__(self, output):
            self.__output = output

        @property
        def output(self):
            """Access the return value of the decorated function. """
            return self.__output


510
511
512
513
514
515
    def __init__(self,
                 func,
                 prepIn,
                 prepOut,
                 load,
                 removeExt,
Paul McCarthy's avatar
Paul McCarthy committed
516
517
                 *args,
                 **kwargs):
Paul McCarthy's avatar
Paul McCarthy committed
518
519
        """Initialise a ``_FileOrThing`` decorator.

520
521
522
523
        :arg func:      The function to be decorated.

        :arg prepIn:    Function which returns a file name to be used in
                        place of an input argument.
524

525
526
        :arg prepOut:   Function which generates a file name to use for
                        arguments that were set to :data:`LOAD`.
Paul McCarthy's avatar
Paul McCarthy committed
527

528
529
530
        :arg load:      Function which is called to load items for arguments
                        that were set to :data:`LOAD`. Must accept a file path
                        as its sole argument.
531

532
533
534
        :arg removeExt: Function which can remove a file extension from a file
                        path.

Paul McCarthy's avatar
Paul McCarthy committed
535
536
537
538
539
540
541
542
543
544
        :arg 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.
545

546
547
548
549
550
551

        The ``prepIn`` and ``prepOut`` functions must accept the following
        positional arguments:

          - A directory in which all temporary input/output files should be
            stored
Paul McCarthy's avatar
Paul McCarthy committed
552

553
554
555
556
          - The name of the keyword argument to be processed

          - The argument value that was passed in
        """
557
558
559
560
        self.__func      = func
        self.__prepIn    = prepIn
        self.__prepOut   = prepOut
        self.__load      = load
561
        self.__removeExt = removeExt
Paul McCarthy's avatar
Paul McCarthy committed
562
563
        self.__things    = args
        self.__outprefix = kwargs.get('outprefix', None)
Paul McCarthy's avatar
Paul McCarthy committed
564
565


566
    def __call__(self, *args, **kwargs):
567
        """Function which calls ``func``, ensuring that any arguments of
Paul McCarthy's avatar
Paul McCarthy committed
568
        type ``Thing`` are saved to temporary files, and any arguments
Paul McCarthy's avatar
Paul McCarthy committed
569
        with the value :data:`LOAD` are loaded and returned.
570

571
        All other arguments are passed through to ``func``.
572
        """
Paul McCarthy's avatar
Paul McCarthy committed
573

574
575
        func     = self.__func
        argnames = namedPositionals(func, args)
576
577

        # Create a tempdir to store any temporary
Paul McCarthy's avatar
Paul McCarthy committed
578
        # input/output things, but don't change
579
580
581
582
        # into it, as file paths passed to the
        # function may be relative.
        with tempdir.tempdir(changeto=False) as td:

583
584
            log.debug('Redirecting LOADed outputs to %s', td)

585
586
            # Replace any things with file names.
            # Also get a list of LOAD outputs
587
            args = self.__prepareArgs(td, argnames, args, kwargs)
588
            args, kwargs, basePrefix, outfiles, prefixes = args
589
590

            # Call the function
591
            result = func(*args, **kwargs)
592

593
            # make a _Results object to store
594
595
596
597
598
599
            # the output. If we are decorating
            # another _FileOrThing, the
            # results will get merged together
            # into a single _Results dict.
            if not isinstance(result, _FileOrThing._Results):
                result = _FileOrThing._Results(result)
600

601
602
            # Load the LOADed outputs
            for oname, ofile in outfiles.items():
603

604
605
606
607
                log.debug('Loading output %s: %s', oname, ofile)

                if op.exists(ofile): oval = self.__load(ofile)
                else:                oval = None
608

609
                result[oname] = oval
610

611
            # Load or move output-prefixed files
612
            if basePrefix is not None:
613

614
615
616
                prefixDir   = op.abspath(op.dirname(basePrefix))
                basePrefix  = op.basename(basePrefix)
                allPrefixed = glob.glob(op.join(td, '{}*'.format(basePrefix)))
617
618
619
620

                for filename in allPrefixed:

                    basename = op.basename(filename)
621
622
                    for prefPat, prefName in prefixes.items():
                        if fnmatch.fnmatch(basename, '{}*'.format(prefPat)):
623

624
625
                            log.debug('Loading prefixed output %s [%s]: %s',
                                      prefPat, prefName, filename)
626

627
628
629
630
631
632
633
634
635
                            # if the load function returns
                            # None, this file is probably
                            # not of the correct type.
                            fval = self.__load(filename)
                            if fval is not None:
                                basename = self.__removeExt(basename)
                                basename = basename.replace(prefPat, prefName)
                                result[basename] = fval
                                break
636
637

                    # if file did not match any pattern,
638
639
640
641
                    # move it into the real prefix, where
                    # the function would have saved it
                    # if we had not modified the prefix
                    # (see __prepareArgs)
642
643
644
645
646
                    else:
                        log.debug('Moving prefixed output %s into %s',
                                  filename, prefixDir)
                        shutil.move(filename, prefixDir)

647
            return result
648
649


650
    def __prepareArgs(self, workdir, argnames, args, kwargs):
651
652
653
654
655
656
657
        """Prepares all input and output arguments to be passed to the
        decorated function. Any arguments with a value of :data:`LOAD` are
        passed to the ``prepOut`` function specified at :meth:`__init__`.
        All other arguments are passed through the ``prepIn`` function.

        :arg workdir: Directory in which all temporary files should be stored.

658
659
660
        :arg args:    Positional arguments to be passed to the decorated
                      function.

661
662
663
664
        :arg kwargs:  Keyword arguments to be passed to the decorated function.

        :returns:     A tuple containing:

665
666
667
                        - An updated copy of ``args``.

                        - An updated copy of ``kwargs``.
668

669
670
671
672
673
674
675
                        - 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.

676
677
                        - A dictionary of ``{ name : filename }`` mappings,
                          for all arguments with a value of ``LOAD``.
678

679
680
                        - A dictionary   ``{ filepat : replstr }`` paths, for
                          all output-prefix arguments with a value of ``LOAD``.
681
682
        """

683
684
685
686
        # These containers keep track
        # of output files which are to
        # be loaded into memory
        outfiles      = dict()
687
        prefixedFiles = dict()
688

689
690
691
        allargs  = {k : v for k, v in zip(argnames, args)}
        allargs.update(kwargs)

692
693
694
695
696
697
698
699
700
701
702
703
704
705
        # Has an output prefix been specified?
        prefix     = allargs.get(self.__outprefix, None)
        realPrefix = None

        # If so, replace it with a new output
        # prefix which will redirect all output
        # to the temp dir.
        #
        # Importantly, here we assume that the
        # underlying function (and hence the
        # underlying command-line tool) will
        # accept an output prefix which contains
        # a directory path.
        if prefix is not None:
706
707
708
709
710
711
712
713
714
715

            # If prefix is set to LOAD,
            # all generated output files
            # should be loaded - we use a
            # randomly generated prefix,
            # and add it to prefixedFiles,
            # so that every file which
            # starts with it will be
            # loaded.
            if prefix is LOAD:
716
717
718
                prefix                = random.sample(string.ascii_letters, 10)
                prefix                = ''.join(prefix)
                prefixedFiles[prefix] = self.__outprefix
719

720
721
722
723
            realPrefix                = prefix
            prefix                    = op.basename(prefix)
            allargs[self.__outprefix] = op.join(workdir, prefix)

724
725
        if len(self.__things) > 0: things = self.__things
        else:                      things = allargs.keys()
726

727
        for name, val in list(allargs.items()):
728

729
730
731
732
733
            # don't process the
            # outprefix argument
            if name == self.__outprefix:
                continue

734
            # is this argument referring
735
            # to a prefixed output?
736
737
            isprefixed = (prefix is not None and
                          name.startswith(prefix))
738

739
            if not (isprefixed or name in things):
740
741
                continue

742
743
744
745
            # Prefixed output files may only
            # be given a value of LOAD
            if isprefixed and val is not LOAD:
                raise ValueError('Cannot specify name of prefixed file - the '
746
747
                                 'name is defined by the output prefix: '
                                 '{}'.format(name))
748

749
            if val is LOAD:
750

751
752
753
754
755
756
757
                # this argument refers to an output
                # that is generated from the output
                # prefix argument, and doesn't map
                # directly to an argument of the
                # function. So we don't pass it
                # through.
                if isprefixed:
758
                    prefixedFiles[name] = name
759
760
761
762
763
                    allargs.pop(name)

                # regular output-file argument
                else:
                    outfile = self.__prepOut(workdir, name, val)
764
                    outfiles[name] = outfile
765
                    allargs[ name] = outfile
Paul McCarthy's avatar
Paul McCarthy committed
766

767
            # Assumed to be an input file
768
            else:
769
                infile = self.__prepIn(workdir, name, val)
Paul McCarthy's avatar
Paul McCarthy committed
770

771
                if infile is not None:
772
773
774
775
                    allargs[name] = infile

        args   = [allargs.pop(k) for k in argnames]
        kwargs = allargs
776

777
        return args, kwargs, realPrefix, outfiles, prefixedFiles
778
779


780
def fileOrImage(*args, **kwargs):
Paul McCarthy's avatar
Paul McCarthy committed
781
782
    """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``
783
    image objects or :class:`.Image` objects.
Paul McCarthy's avatar
Paul McCarthy committed
784
785
    """

786
787
788
789
790
791
    # keep track of the input argument
    # types on each call, so we know
    # whether to return a fsl.Image or
    # a nibabel image
    intypes = []

792
    def prepIn(workdir, name, val):
Paul McCarthy's avatar
Paul McCarthy committed
793

794
        infile = None
Paul McCarthy's avatar
Paul McCarthy committed
795

796
797
798
799
800
801
        if isinstance(val, (fslimage.Image, nib.nifti1.Nifti1Image)):
            intypes.append(type(val))

        if isinstance(val, fslimage.Image):
            val = val.nibImage

Paul McCarthy's avatar
Paul McCarthy committed
802
        if isinstance(val, nib.nifti1.Nifti1Image):
803
            infile = val.get_filename()
Paul McCarthy's avatar
Paul McCarthy committed
804
805
806

            # in-memory image - we have
            # to save it out to a file
807
808
            if infile is None:
                hd, infile = tempfile.mkstemp(fslimage.defaultExt())
Paul McCarthy's avatar
Paul McCarthy committed
809
                os.close(hd)
810
                val.to_filename(infile)
Paul McCarthy's avatar
Paul McCarthy committed
811

812
        return infile
Paul McCarthy's avatar
Paul McCarthy committed
813

814
815
    def prepOut(workdir, name, val):
        return op.join(workdir, '{}.nii.gz'.format(name))
Paul McCarthy's avatar
Paul McCarthy committed
816

817
    def load(path):
818
819
820
821

        if not fslimage.looksLikeImage(path):
            return None

Paul McCarthy's avatar
Paul McCarthy committed
822
823
824
        # create an independent in-memory
        # copy of the image file
        img = nib.load(path)
825
826
827
828
829
830
831
832
833
834
835
836
837
838

        # if any arguments were fsl images,
        # that takes precedence.
        if fslimage.Image in intypes:
            return fslimage.Image(img.get_data(), header=img.header)
        # but if all inputs were file names,
        # nibabel takes precedence
        elif nib.nifti1.Nifti1Image in intypes or len(intypes) == 0:
            return nib.nifti1.Nifti1Image(img.get_data(), None, img.header)

        # this function should not be called
        # under any other circumstances
        else:
            raise RuntimeError('Cannot handle type: {}'.format(intypes))
Paul McCarthy's avatar
Paul McCarthy committed
839

840
    def decorator(func):
841
842
843
844
845
846
847
        fot = _FileOrThing(func,
                           prepIn,
                           prepOut,
                           load,
                           fslimage.removeExt,
                           *args,
                           **kwargs)
848
849

        def wrapper(*args, **kwargs):
850
851
852
            result = fot(*args, **kwargs)
            intypes[:] = []
            return result
853
854
855
856

        return _update_wrapper(wrapper, func)

    return decorator
Paul McCarthy's avatar
Paul McCarthy committed
857
858


859
def fileOrArray(*args, **kwargs):
Paul McCarthy's avatar
Paul McCarthy committed
860
861
862
863
    """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.
    """

864
    def prepIn(workdir, name, val):
Paul McCarthy's avatar
Paul McCarthy committed
865

866
        infile = None
Paul McCarthy's avatar
Paul McCarthy committed
867
868

        if isinstance(val, np.ndarray):
869
            hd, infile = tempfile.mkstemp('.txt')
Paul McCarthy's avatar
Paul McCarthy committed
870
            os.close(hd)
871
            np.savetxt(infile, val, fmt='%0.18f')
Paul McCarthy's avatar
Paul McCarthy committed
872

873
        return infile
Paul McCarthy's avatar
Paul McCarthy committed
874

875
876
    def prepOut(workdir, name, val):
        return op.join(workdir, '{}.txt'.format(name))
Paul McCarthy's avatar
Paul McCarthy committed
877

878
879
880
    def load(path):
        try:              return np.loadtxt(path)
        except Exception: return None
Paul McCarthy's avatar
Paul McCarthy committed
881

882
    def decorator(func):
883
884
885
886
887
888
889
        fot = _FileOrThing(func,
                           prepIn,
                           prepOut,
                           load,
                           fslpath.removeExt,
                           *args,
                           **kwargs)
890
891
892
893
894
895
896

        def wrapper(*args, **kwargs):
            return fot(*args, **kwargs)

        return _update_wrapper(wrapper, func)

    return decorator