Merge branch 'enh/fslstats' into 'master'

Enh/fslstats

See merge request fsl/fslpy!213

CHANGELOG.rst

@@ -2,16 +2,16 @@ This document contains the ``fslpy`` release history in reverse chronological
 order.
 
 
-3.0.0 (Under development)
--------------------------
+3.0.0 (Sunday 29th March 2020)
+------------------------------
 
 
 Added
 ^^^^^
 
 
-* New wrapper functions for the FSL :func:`.prelude` and :func:`applyxfm4D`
-  commands.
+* New wrapper functions for the FSL :class:`.fslstats`, :func:`.prelude` and
+  :func:`applyxfm4D` commands.
 * New ``firstDot`` option to the :func:`.path.getExt`,
   :func:`.path.removeExt`, and :func:`.path.splitExt`, functions, offering
   rudimentary support for double-barrelled filenames.
@@ -19,6 +19,7 @@ Added
   affine, which is applied to the input image before the deformation field.
 * New :class:`.SubmitParams` class, providing a higer level interface for
   cluster submission.
+* New :meth:`.FileTree.load_json` and  :meth:`.FileTree.save_json` methods.
 
 
 Changed
@@ -26,6 +27,10 @@ Changed
 
 
 * ``fslpy`` now requires a minimum Python version of 3.7.
+* The default value for the ``partial_fill`` option to :meth:`.FileTree.read`
+  has been changed to ``False``. Accordingly, the :class:`.FileTreeQuery`
+  calls the :meth:`.FileTree.partial_fill` method on the ``FileTree`` it is
+  given.
 * The :func:`.gifti.relatedFiles` function now supports files with
   BIDS-style naming conventions.
 * The :func:`.run.run` and :func:`.run.runfsl` functions now pass through any
@@ -54,6 +59,8 @@ Changed
 * The :func:`.fileOrText` decorator has been updated to work with input
   values - file paths must be passed in as ``pathlib.Path`` objects, so they
   can be differentiated from input values.
+* Loaded :class:`.Image` objects returned by :mod:`fsl.wrappers` functions
+  are now named according to the wrapper function argument name.
 
 
 Fixed
@@ -69,6 +76,24 @@ Fixed
   a single set of coordinates.
 
 
+Removed
+^^^^^^^
+
+
+* Removed the deprecated ``.StatisticAtlas.proportions``,
+  ``.StatisticAtlas.coordProportions``, and
+  ``.StatisticAtlas.maskProportions`` methods.
+* Removed the deprecated ``indexed`` option to :meth:`.Image.__init__`.
+* Removed the deprecated ``.Image.resample`` method.
+* Removed the deprecated ``.image.loadIndexedImageFile`` function.
+* Removed the deprecatd ``.FileTreeQuery.short_names`` and
+  ``.Match.short_name`` properties.
+* Removed the deprecated ``.idle.inIdle``, ``.idle.cancelIdle``,
+  ``.idle.idleReset``, ``.idle.getIdleTimeout``, and
+  ``.idle.setIdleTimeout`` functions.
+* Removed the deprecated ``resample.calculateMatrix`` function.
+
+
 2.8.4 (Monday 2nd March 2020)
 -----------------------------
 

fsl/data/atlases.py

@@ -58,7 +58,6 @@ import fsl.utils.image.resample as resample
 import fsl.transform.affine     as affine
 import fsl.utils.notifier       as notifier
 import fsl.utils.settings       as fslsettings
-import fsl.utils.deprecated     as deprecated
 
 
 log = logging.getLogger(__name__)
@@ -1085,24 +1084,6 @@ class StatisticAtlas(Atlas):
         return avgvals
 
 
-    @deprecated.deprecated('2.6.0', '3.0.0', 'Use values instead')
-    def proportions(self, *args, **kwargs):
-        """Deprecated - use :meth:`values` instead. """
-        return self.values(*args, **kwargs)
-
-
-    @deprecated.deprecated('2.6.0', '3.0.0', 'Use coordValues instead')
-    def coordProportions(self, *args, **kwargs):
-        """Deprecated - use :meth:`coordValues` instead. """
-        return self.coordValues(*args, **kwargs)
-
-
-    @deprecated.deprecated('2.6.0', '3.0.0', 'Use maskValues instead')
-    def maskProportions(self, *args, **kwargs):
-        """Deprecated - use :meth:`maskValues` instead. """
-        return self.maskValues(*args, **kwargs)
-
-
 class ProbabilisticAtlas(StatisticAtlas):
     """A 4D atlas which contains one volume for each region. Each volume
     contains probabiliy values for one region, between 0 and 100.

fsl/data/image.py

@@ -52,7 +52,6 @@ import fsl.transform.affine  as affine
 import fsl.utils.notifier    as notifier
 import fsl.utils.memoize     as memoize
 import fsl.utils.path        as fslpath
-import fsl.utils.deprecated  as deprecated
 import fsl.utils.bids        as fslbids
 import fsl.data.constants    as constants
 import fsl.data.imagewrapper as imagewrapper
@@ -993,7 +992,6 @@ class Image(Nifti):
                  xform=None,
                  loadData=True,
                  calcRange=True,
-                 indexed=False,
                  threaded=False,
                  dataSource=None,
                  loadMeta=False,
@@ -1002,7 +1000,7 @@ class Image(Nifti):
 
         :arg image:      A string containing the name of an image file to load,
                          or a :mod:`numpy` array, or a :mod:`nibabel` image
-                         object.
+                         object, or an ``Image``object.
 
         :arg name:       A name for the image.
 
@@ -1035,9 +1033,6 @@ class Image(Nifti):
                          incrementally updated as more data is read from memory
                          or disk.
 
-        :arg indexed:    Deprecated. Has no effect, and will be removed in
-                         ``fslpy`` 3.0.
-
         :arg threaded:   If ``True``, the :class:`.ImageWrapper` will use a
                          separate thread for data range calculation. Defaults
                          to ``False``. Ignored if ``loadData`` is ``True``.
@@ -1059,12 +1054,6 @@ class Image(Nifti):
         nibImage = None
         saved    = False
 
-        if indexed is not False:
-            warnings.warn('The indexed argument is deprecated '
-                          'and has no effect',
-                          category=DeprecationWarning,
-                          stacklevel=2)
-
         if loadData:
             threaded = False
 
@@ -1463,14 +1452,6 @@ class Image(Nifti):
         self.notify(topic='saveState')
 
 
-    @deprecated.deprecated('2.2.0', '3.0.0',
-                           'Use fsl.utils.image.resample instead.')
-    def resample(self, *args, **kwargs):
-        """Deprecated - use :func:`.image.resample` instead. """
-        from fsl.utils.image.resample import resample
-        return resample(self, *args, **kwargs)
-
-
     def __getitem__(self, sliceobj):
         """Access the image data with the specified ``sliceobj``.
 
@@ -1661,9 +1642,3 @@ def defaultExt():
     outputType = os.environ.get('FSLOUTPUTTYPE', 'NIFTI_GZ')
 
     return options.get(outputType, '.nii.gz')
-
-
-@deprecated.deprecated('2.0.0', '3.0.0', 'Use nibabel.load instead.')
-def loadIndexedImageFile(filename):
-    """Deprecated - this call is equivalent to calling ``nibabel.load``. """
-    return nib.load(filename)

fsl/utils/filetree/query.py

@@ -31,8 +31,7 @@ from typing import Dict, List, Tuple
 
 import numpy as np
 
-from fsl.utils.deprecated import deprecated
-from .                    import FileTree
+from . import FileTree
 
 
 log = logging.getLogger(__name__)
@@ -207,15 +206,6 @@ class FileTreeQuery(object):
         return list(self.__templatevars.keys())
 
 
-    @property
-    @deprecated('2.6.0', '3.0.0', 'Use templates instead')
-    def short_names(self) -> List[str]:
-        """Returns a list containing all templates of the ``FileTree`` that
-        are present in the directory.
-        """
-        return self.templates
-
-
     def query(self, template, asarray=False, **variables):
         """Search for files of the given ``template``, which match
         the specified ``variables``. All hits are returned for variables
@@ -292,12 +282,6 @@ class Match(object):
         return self.__filename
 
 
-    @property
-    @deprecated('2.6.0', '3.0.0', 'Use template instead')
-    def short_name(self):
-        return self.template
-
-
     @property
     def template(self):
         return self.__template

fsl/utils/idle.py

@@ -85,8 +85,6 @@ from   collections import abc
 try:                import queue
 except ImportError: import Queue as queue
 
-from fsl.utils.deprecated import deprecated
-
 
 log = logging.getLogger(__name__)
 
@@ -597,36 +595,6 @@ def idleWhen(*args, **kwargs):
     idleLoop.idleWhen(*args, **kwargs)
 
 
-@deprecated('2.7.0', '3.0.0', 'Use idleLoop.inIdle instead')
-def inIdle(taskName):
-    """Deprecated - use ``idleLoop.inIdle`` instead. """
-    return idleLoop.inIdle(taskName)
-
-
-@deprecated('2.7.0', '3.0.0', 'Use idleLoop.cancelIdle instead')
-def cancelIdle(taskName):
-    """Deprecated - use ``idleLoop.cancelIdle`` instead. """
-    return idleLoop.cancelIdle(taskName)
-
-
-@deprecated('2.7.0', '3.0.0', 'Use idleLoop.reset instead')
-def idleReset():
-    """Deprecated - use ``idleLoop.reset`` instead. """
-    return idleLoop.reset()
-
-
-@deprecated('2.7.0', '3.0.0', 'Use idleLoop.callRate instead')
-def getIdleTimeout():
-    """Deprecated - use ``idleLoop.callRate`` instead. """
-    return idleLoop.callRate
-
-
-@deprecated('2.7.0', '3.0.0', 'Use idleLoop.callRate instead')
-def setIdleTimeout(timeout=None):
-    """Deprecated - use ``idleLoop.callRate`` instead. """
-    idleLoop.callRate = timeout
-
-
 def block(secs, delta=0.01, until=None):
     """Blocks for the specified number of seconds, yielding to the main ``wx``
     loop.

fsl/utils/image/resample.py

@@ -18,7 +18,6 @@ import numpy                as np
 import scipy.ndimage        as ndimage
 
 import fsl.transform.affine as affine
-import fsl.utils.deprecated as deprecated
 
 
 def resampleToPixdims(image, newPixdims, **kwargs):
@@ -282,13 +281,3 @@ def applySmoothing(data, matrix, newShape):
     sigma[ratio >= 1.1] *= 0.425
 
     return ndimage.gaussian_filter(data, sigma)
-
-
-@deprecated.deprecated('2.8.0', '3.0.0',
-                       'Use fsl.transform.affine.rescale instead')
-def calculateMatrix(oldShape, newShape, origin):
-    """Deprecated - use :func:`.affine.rescale` instead. """
-    xform = affine.rescale(oldShape, newShape, origin)
-    if np.all(np.isclose(xform, np.eye(len(oldShape) + 1))):
-        return None
-    return xform[:-1, :]

fsl/utils/run.py

@@ -180,13 +180,17 @@ def run(*args, **kwargs):
     returnStderr   = kwargs.pop('stderr',   False)
     returnExitcode = kwargs.pop('exitcode', False)
     submit         = kwargs.pop('submit',   {})
-    log            = kwargs.pop('log',      {})
-    tee            = log   .get('tee',      False)
-    logStdout      = log   .get('stdout',   None)
-    logStderr      = log   .get('stderr',   None)
-    logCmd         = log   .get('cmd',      None)
+    log            = kwargs.pop('log',      None)
     args           = prepareArgs(args)
 
+    if log is None:
+        log = {}
+
+    tee       = log.get('tee',    False)
+    logStdout = log.get('stdout', None)
+    logStderr = log.get('stderr', None)
+    logCmd    = log.get('cmd',    None)
+
     if not bool(submit):
         submit = None
 

fsl/utils/transform.py

-#!/usr/bin/env python
-#
-# transforms.py - Deprecated
-#
-# Author: Paul McCarthy <pauldmccarthy@gmail.com>
-#
-"""The ``fsl.utils.transform`` module is deprecated - use the
-:mod:`fsl.transform` module instead.
-"""
-
-
-import fsl.utils.deprecated as     deprecated
-from   fsl.transform.affine import *                     # noqa
-from   fsl.transform.flirt  import (flirtMatrixToSform,  # noqa
-                                    sformToFlirtMatrix)
-
-
-deprecated.warn('fsl.utils.transform',
-                vin='2.4.0',
-                rin='3.0.0',
-                msg='Use the fsl.transform module instead')

fsl/version.py

@@ -47,7 +47,7 @@ import            re
 import            string
 
 
-__version__ = '2.9.0.dev0'
+__version__ = '3.1.0.dev0'
 """Current version number, as a string. """
 
 

fsl/wrappers/__init__.py

@@ -37,12 +37,15 @@ instead. Aliases may also be used to provide a more readable interface (e.g.
 the :func:`.bet` function uses ``mask`` instead of ``m``).
 
 
-One exception to the above is :class:`.fslmaths`, which provides a more
-object-oriented interface::
+Two exceptions to the above are :class:`.fslmaths` and :class:`.fslstats`,
+which provide a more object-oriented interface::
+
+    from fsl.wrappers import fslmaths, fslstats
 
-    from fsl.wrappers import fslmaths
     fslmaths('image.nii').mas('mask.nii').bin().run('output.nii')
 
+    imean, imin, imax = fslstats('image.nii').k('mask.nii').m.R.run()
+
 
 Wrapper functions for commands which accept NIfTI image or numeric text files
 will for the most part accept either in-memory ``nibabel`` images/Numpy arrays
@@ -95,6 +98,7 @@ from .fnirt        import (fnirt,           # noqa
                            invwarp,
                            convertwarp)
 from .fslmaths     import (fslmaths,)       # noqa
+from .fslstats     import (fslstats,)       # noqa
 from .fugue        import (fugue,           # noqa
                            prelude,
                            sigloss)

fsl/wrappers/fslstats.py

+#!/usr/bin/env python
+#
+# fslstats.py - Wrapper for fslstats
+#
+# Author: Paul McCarthy <pauldmccarthy@gmail.com>
+#
+"""This module provides the :class:`fslstats` class, which acts as a wrapper
+for the ``fslstats`` command-line tool.
+
+
+.. warning:: This wrapper function will only work with FSL 6.0.2 or newer.
+"""
+
+
+import              io
+import functools as ft
+import numpy     as np
+
+import fsl.data.image      as fslimage
+from . import wrapperutils as wutils
+
+
+class fslstats(object):
+    """The ``fslstats`` class is a wrapper around the ``fslstats`` command-line
+    tool. It provides an object-oriented interface - options are specified by
+    chaining method calls and attribute accesses together.
+
+
+    .. warning:: This wrapper function will only work with FSL 6.0.2 or newer,
+                 due to bugs in ``fslstats`` output formatting that are
+                 present in older versions.
+
+
+    Any ``fslstats`` command-line option which does not require any arguments
+    (e.g. ``-r``) can be set by accessing an attribute on a ``fslstats``
+    object, e.g.::
+
+        stats = fslstats('image.nii.gz')
+        stats.r
+
+
+    ``fslstats`` command-line options which do require additional arguments
+    (e.g. ``-k``) can be set by calling a method on an ``fslstats`` object,
+    e.g.::
+
+        stats = fslstats('image.nii.gz')
+        stats.k('mask.nii.gz')
+
+
+    The ``fslstats`` command can be executed via the :meth:`run` method.
+    Normally, the results will be returned as a scalar floating point number,
+    or a ``numpy`` array. Pre-options will affect the structure of the return
+    value - see :meth:`__init__` for details.
+
+
+    Attribute and method calls can be chained together, so a complete
+    ``fslstats`` call can be performed in a single line, e.g.::
+
+        imgmin, imgmax = fslstats('image.nii.gz').k('mask.nii.gz').r.run()
+    """
+
+    OPTIONS = {
+        'robust_minmax'   : 'r',
+        'minmax'          : 'R',
+        'mean_entropy'    : 'e',
+        'mean_entropy_nz' : 'E',
+        'volume'          : 'v',
+        'volume_nz'       : 'V',
+        'mean'            : 'm',
+        'mean_nz'         : 'M',
+        'stddev'          : 's',
+        'stddev_nz'       : 'S',
+        'smallest_roi'    : 'w',
+        'max_vox'         : 'x',
+        'min_vox'         : 'X',
+        'cog_mm'          : 'c',
+        'cog_vox'         : 'C',
+        'abs'             : 'a',
+        'zero_naninf'     : 'n',
+    }
+    """This dict contains options which do not require any additional
+    arguments. They are set via attribute access on the ``fslstats``
+    object.
+    """
+
+
+    ARG_OPTIONS = {
+        'lower_threshold' : 'l',
+        'upper_threshold' : 'u',
+        'percentile'      : 'p',
+        'percentile_nz'   : 'P',
+        'mask'            : 'k',
+        'diff'            : 'd',
+        'hist'            : 'h',
+        'hist_bounded'    : 'H',
+    }
+    """This dict contains options which require additional arguments.
+    They are set via method calls on the ``fslstats`` object (with the
+    additional arguments passed into the method call).
+    """
+
+
+    # add {shortopt : shortopt} mappings
+    # for all options to simplify code in
+    # the  fslstats class
+    OPTIONS    .update({v : v for v in OPTIONS    .values()})
+    ARG_OPTIONS.update({v : v for v in ARG_OPTIONS.values()})
+
+
+    def __init__(self,
+                 input,
+                 t=False,
+                 K=None,
+                 sep_volumes=False,
+                 index_mask=None):
+        """Create a ``fslstats`` object.
+
+        If one of the ``t`` or ``K`` pre-options is set, e.g.::
+
+            fslstats('image_4d.nii.gz', t=True)
+
+        or::
+
+            fslstats('image_4d.nii.gz', K='mask.nii.gz')
+
+        then :meth:`run` will return a 2D ``numpy`` array of shape ``(nvols,
+        nvals)`` if ``t`` is set, or ``(nlabels, nvals)`` if ``K`` is set.
+
+        If both of the ``t`` and ``K`` pre-options are set, e.g.::
+
+            fslstats('image_4d.nii.gz', t=True, K='mask.nii.gz')
+
+        then the result will be a 3D numpy array of shape ``(nvols, nlabels,
+        nvals)``.
+
+        If neither ``t`` or ``K`` are set, then the result will be a scalar,
+        or a 1D ``numpy`` array.
+
+        :arg input:       Input image - either a file name, or an
+                          :class:`.Image` object, or a ``nibabel.Nifti1Image``
+                          object.
+        :arg t:           Produce separate results for each 3D volume in the
+                          input image.
+        :arg K:           Produce separate results for each sub-mask within
+                          the provided mask image.
+        :arg sep_volumes: Alias for ``t``.
+        :arg index_mask:  Alias for ``K``.
+        """
+
+        if t is None: t = sep_volumes
+        if K is None: K = index_mask