wrapperutils.py 22.8 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
27
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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
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.


.. note:: The :func:`fslwrapper` and :func:`cmdwrapper` should always be
          the _first_ decorator applied to a function.


The :func:`applyArgStyle` function can be used to automatically generate
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.


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
76
"""
77
78
79
80


import os.path as op
import            os
Paul McCarthy's avatar
Paul McCarthy committed
81
import            sys
82
83
84
85
86
87
88
89
import            inspect
import            tempfile
import            warnings
import            functools
import            collections

import            six
import nibabel as nib
Paul McCarthy's avatar
Paul McCarthy committed
90
import numpy   as np
91
92

import fsl.utils.tempdir as tempdir
93
import fsl.utils.run     as run
94
95
96
import fsl.data.image    as fslimage


Paul McCarthy's avatar
Paul McCarthy committed
97
98
99
100
101
102
103
104
105
106
107
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.

    This behaviour is only required in Python versions < 3.4.
    """

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

    # Python >= 3.4 does things right
Paul McCarthy's avatar
Paul McCarthy committed
108
    if (sys.version_info[0] * 10 + sys.version_info[1]) < 34:
Paul McCarthy's avatar
Paul McCarthy committed
109
110
        wrapper.__wrapped__ = wrapped
    return wrapper
111
112


Paul McCarthy's avatar
Paul McCarthy committed
113
114
115
116
117
118
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
119
    if (sys.version_info[0] * 10 + sys.version_info[1]) >= 34:
Paul McCarthy's avatar
Paul McCarthy committed
120
121
122
123
124
125
126
127
128
        return inspect.unwrap(func)

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

    return func


129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
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):
        cmd = func(*args, **kwargs)
        return run.run(cmd, err=True)
    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):
        cmd = func(*args, **kwargs)
        return run.runfsl(cmd, err=True)
    return _update_wrapper(wrapper, func)


Paul McCarthy's avatar
Paul McCarthy committed
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
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.
"""
167
168


169
def applyArgStyle(style, valsep=None, argmap=None, valmap=None, **kwargs):
Paul McCarthy's avatar
Paul McCarthy committed
170
171
172
173
    """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.

174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
    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
196
    :arg style:  Controls how the ``kwargs`` are converted into command-line
197
198
199
200
201
                 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
202
203
                 one of ``' '``, ``','`` or ``'"'``. Defaults to ``' '``
                 if ``'=' not in style``, ``','`` otherwise.
Paul McCarthy's avatar
Paul McCarthy committed
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226

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

Paul McCarthy's avatar
Paul McCarthy committed
228
229
230
231
232
    :arg kwargs: Arguments to be converted into command-line options.

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

233
234
235
236
    if valsep is None:
        if '=' in style: valsep = ','
        else:            valsep = ' '

Paul McCarthy's avatar
Paul McCarthy committed
237
238
    if style not in ('-', '--', '-=', '--='):
        raise ValueError('Invalid style: {}'.format(style))
239
240
241
242
243
244
245
246
247
    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
248
249
250
251
252

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

    def fmtarg(arg):
253
254
255
256
        if   style in ('-',  '-='):  arg =  '-{}'.format(arg)
        elif style in ('--', '--='): arg = '--{}'.format(arg)
        return arg

257
    # always returns a sequence
Paul McCarthy's avatar
Paul McCarthy committed
258
    def fmtval(val):
259
260
        if     isinstance(val, collections.Sequence) and \
           not isinstance(val, six.string_types):
261
262
263
264
265

            val = [str(v) for v in val]
            if   valsep == ' ': return val
            elif valsep == '"': return [' '   .join(val)]
            else:               return [valsep.join(val)]
266
        else:
267
268
269
270
271
272
273
274
            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
275
276
277
278
279
280

    args = []

    for k, v in kwargs.items():

        k    = argmap.get(k, k)
Paul McCarthy's avatar
Paul McCarthy committed
281
282
283
        mapv = valmap.get(k, fmtval(v))
        k    = fmtarg(k)

284

285
286
287
288
        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)
289
        else:
290
            args.extend(fmtargval(k, mapv))
291
292
293
294
295

    return args


def required(*reqargs):
296
297
298
299
300
301
302
    """Decorator which makes sure that all specified arguments are present
    before calling the decorated function. Arguments which are not present
    will result in an :exc:`AssertionError`. Use as follows::

        @required('foo')
        def funcWhichRequires_foo(**kwargs):
            foo = kwargs['foo']
303
    """
Paul McCarthy's avatar
Paul McCarthy committed
304

305
    def decorator(func):
Paul McCarthy's avatar
Paul McCarthy committed
306
        def wrapper(*args, **kwargs):
307
            argnames = namedPositionals(func, args)
308
            for reqarg in reqargs:
309
                assert (reqarg in kwargs) or (reqarg in argnames)
310
            return func(**kwargs)
311
        return _update_wrapper(wrapper, func)
312
313
314
    return decorator


315
def namedPositionals(func, args):
316
    """Given a function, and a sequence of positional arguments destined
317
318
    for that function, identiifes the name for each positional argument.
    Variable positional arguments are given an automatic name.
319

320
321
    :arg func: Function which will accept ``args`` as positionals.
    :arg args: Tuple of positional arguments to be passed to ``func``.
322
    """
Paul McCarthy's avatar
Paul McCarthy committed
323

324
325
326
327
328
329
330
331
332
333
    # 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?

334
335
    # Remove any decorators
    # from the function
Paul McCarthy's avatar
Paul McCarthy committed
336
337
    func = _unwrap(func)

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

346
347
    # But getargspec is deprecated
    # in python 3.x
Paul McCarthy's avatar
Paul McCarthy committed
348
349
350
351
352
353
    else:

        # getfullargspec is deprecated in
        # python 3.5, but not in python 3.6.
        with warnings.catch_warnings():
            warnings.filterwarnings('ignore', category=DeprecationWarning)
354
355
356
            spec     = inspect.getfullargspec(func)
            argnames = spec.args
            varargs  = spec.varargs
357

358
359
360
    # we only care about the arguments
    # that are being passed in
    argnames = argnames[:len(args)]
361

362
363
364
365
    # 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)]
366

367
    return argnames
368
369


Paul McCarthy's avatar
Paul McCarthy committed
370
LOAD = object()
Paul McCarthy's avatar
Paul McCarthy committed
371
372
"""Constant used by the :class:`_FileOrThing` class to indicate that an output
file should be loaded into memory and returned as a Python object.
373
374
375
"""


Paul McCarthy's avatar
Paul McCarthy committed
376
377
378
379
380
381
382
383
384
385
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.

386

Paul McCarthy's avatar
Paul McCarthy committed
387
388
389
390
391
392
393
394
395
396
397
398
    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.

399

Paul McCarthy's avatar
Paul McCarthy committed
400
    **Outputs**
401
402


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


    **Return value**


    Functions decorated with a ``_FileOrThing`` decorator will always return a
414
415
416
417
418
    ``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
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442


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

443
444
            return 'Done'

Paul McCarthy's avatar
Paul McCarthy committed
445
446
447
448

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

449

Paul McCarthy's avatar
Paul McCarthy committed
450
451
        # All arguments are passed through
        # unmodified - the output will be
452
        # saved to a file called atoc.mat.
Paul McCarthy's avatar
Paul McCarthy committed
453
454
        concat('atob.txt', 'btoc.txt', 'atoc.mat')

455
456
457
458
459
460
461
462
463
        # 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
464

465
466
467
468
469
470
471
472
473
        # 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
474
475
476
477
478
479
480
481
482
483


    ``_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
    __as long as__ they do not manipulate the return value.
484
485
486
    """


487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
    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


505
    def __init__(self, func, prepIn, prepOut, load, *things):
Paul McCarthy's avatar
Paul McCarthy committed
506
507
        """Initialise a ``_FileOrThing`` decorator.

508
509
        :arg func:    The function to be decorated.

510
511
        :arg prepIn:  Function which returns a file name to be used in
                      place of an input argument.
Paul McCarthy's avatar
Paul McCarthy committed
512

513
514
        :arg prepOut: Function which generates a file name to use for
                      arguments that were set to :data:`LOAD`.
515

516
517
518
        :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.
519

520
        :arg things:  Names of all arguments which will be handled by
521
522
523
                      this ``_FileOrThing`` decorator. If not provided,
                      *all* arguments passed to the function will be
                      handled.
524
525
526
527
528
529

        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
530

531
532
533
534
          - The name of the keyword argument to be processed

          - The argument value that was passed in
        """
535
        self.__func    = func
536
537
538
539
        self.__prepIn  = prepIn
        self.__prepOut = prepOut
        self.__load    = load
        self.__things  = things
Paul McCarthy's avatar
Paul McCarthy committed
540
541


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

547
        All other arguments are passed through to ``func``.
548
        """
Paul McCarthy's avatar
Paul McCarthy committed
549

550
551
        func     = self.__func
        argnames = namedPositionals(func, args)
552
553

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

559
560
            # Replace any things with file names.
            # Also get a list of LOAD outputs
561
562
            args, kwargs, outfiles = self.__prepareArgs(
                td, argnames, args, kwargs)
563
564

            # Call the function
565
            result = func(*args, **kwargs)
566

567
568
569
570
571
572
573
            # make a _Reults object to store
            # 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)
574

575
576
            # Load the LOADed outputs
            for oname, ofile in outfiles.items():
577

578
579
                if not op.exists(ofile): oval = None
                else:                    oval = self.__load(ofile)
580

581
                result[oname] = oval
582

583
            return result
584
585


586
    def __prepareArgs(self, workdir, argnames, args, kwargs):
587
588
589
590
591
592
593
        """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.

594
595
596
        :arg args:    Positional arguments to be passed to the decorated
                      function.

597
598
599
600
        :arg kwargs:  Keyword arguments to be passed to the decorated function.

        :returns:     A tuple containing:

601
602
603
                        - An updated copy of ``args``.

                        - An updated copy of ``kwargs``.
604
605
606

                        - A dictionary of ``{ name : filename }`` mappings,
                          for all arguments with a value of ``LOAD``.
607
608
        """

609
        outfiles = dict()
610

611
612
613
        allargs  = {k : v for k, v in zip(argnames, args)}
        allargs.update(kwargs)

614
615
        if len(self.__things) > 0: things = self.__things
        else:                      things = allargs.keys()
616

617
618
619
        for name in things:

            val = allargs.get(name, None)
620

621
            if val is None:
622
623
                continue

624
            if val is LOAD:
625
626
627
628

                outfile = self.__prepOut(workdir, name, val)

                if outfile is not None:
629
                    allargs[ name] = outfile
630
631
                    outfiles[name] = outfile
            else:
Paul McCarthy's avatar
Paul McCarthy committed
632

633
                infile = self.__prepIn(workdir, name, val)
Paul McCarthy's avatar
Paul McCarthy committed
634

635
                if infile is not None:
636
637
638
639
                    allargs[name] = infile

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

641
        return args, kwargs, outfiles
642
643


Paul McCarthy's avatar
Paul McCarthy committed
644
645
646
647
648
649
def fileOrImage(*imgargs):
    """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.
    """

650
    def prepIn(workdir, name, val):
Paul McCarthy's avatar
Paul McCarthy committed
651

652
        infile = None
Paul McCarthy's avatar
Paul McCarthy committed
653
654

        if isinstance(val, nib.nifti1.Nifti1Image):
655
            infile = val.get_filename()
Paul McCarthy's avatar
Paul McCarthy committed
656
657
658

            # in-memory image - we have
            # to save it out to a file
659
660
            if infile is None:
                hd, infile = tempfile.mkstemp(fslimage.defaultExt())
Paul McCarthy's avatar
Paul McCarthy committed
661
                os.close(hd)
662
                val.to_filename(infile)
Paul McCarthy's avatar
Paul McCarthy committed
663

664
        return infile
Paul McCarthy's avatar
Paul McCarthy committed
665

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

669
    def load(path):
Paul McCarthy's avatar
Paul McCarthy committed
670
671
672
673
674
        # create an independent in-memory
        # copy of the image file
        img = nib.load(path)
        return nib.nifti1.Nifti1Image(img.get_data(), None, img.header)

675
676
677
678
679
680
681
682
683
    def decorator(func):
        fot = _FileOrThing(func, prepIn, prepOut, load, *imgargs)

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

        return _update_wrapper(wrapper, func)

    return decorator
Paul McCarthy's avatar
Paul McCarthy committed
684
685
686
687
688
689
690


def fileOrArray(*arrargs):
    """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.
    """

691
    def prepIn(workdir, name, val):
Paul McCarthy's avatar
Paul McCarthy committed
692

693
        infile = None
Paul McCarthy's avatar
Paul McCarthy committed
694
695

        if isinstance(val, np.ndarray):
696
            hd, infile = tempfile.mkstemp('.txt')
Paul McCarthy's avatar
Paul McCarthy committed
697
            os.close(hd)
698
            np.savetxt(infile, val, fmt='%0.18f')
Paul McCarthy's avatar
Paul McCarthy committed
699

700
        return infile
Paul McCarthy's avatar
Paul McCarthy committed
701

702
703
    def prepOut(workdir, name, val):
        return op.join(workdir, '{}.txt'.format(name))
Paul McCarthy's avatar
Paul McCarthy committed
704

705
    load = np.loadtxt
Paul McCarthy's avatar
Paul McCarthy committed
706

707
708
709
710
711
712
713
714
715
    def decorator(func):
        fot = _FileOrThing(func, prepIn, prepOut, load, *arrargs)

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

        return _update_wrapper(wrapper, func)

    return decorator