Commit 0a972e0c authored by Paul McCarthy's avatar Paul McCarthy 🚵
Browse files

Merge branch 'enh/fslstats' into 'master'

Enh/fslstats

See merge request fsl/fslpy!213
parents 85609e78 2e47fd50
...@@ -2,16 +2,16 @@ This document contains the ``fslpy`` release history in reverse chronological ...@@ -2,16 +2,16 @@ This document contains the ``fslpy`` release history in reverse chronological
order. order.
3.0.0 (Under development) 3.0.0 (Sunday 29th March 2020)
------------------------- ------------------------------
Added Added
^^^^^ ^^^^^
* New wrapper functions for the FSL :func:`.prelude` and :func:`applyxfm4D` * New wrapper functions for the FSL :class:`.fslstats`, :func:`.prelude` and
commands. :func:`applyxfm4D` commands.
* New ``firstDot`` option to the :func:`.path.getExt`, * New ``firstDot`` option to the :func:`.path.getExt`,
:func:`.path.removeExt`, and :func:`.path.splitExt`, functions, offering :func:`.path.removeExt`, and :func:`.path.splitExt`, functions, offering
rudimentary support for double-barrelled filenames. rudimentary support for double-barrelled filenames.
...@@ -19,6 +19,7 @@ Added ...@@ -19,6 +19,7 @@ Added
affine, which is applied to the input image before the deformation field. affine, which is applied to the input image before the deformation field.
* New :class:`.SubmitParams` class, providing a higer level interface for * New :class:`.SubmitParams` class, providing a higer level interface for
cluster submission. cluster submission.
* New :meth:`.FileTree.load_json` and :meth:`.FileTree.save_json` methods.
Changed Changed
...@@ -26,6 +27,10 @@ Changed ...@@ -26,6 +27,10 @@ Changed
* ``fslpy`` now requires a minimum Python version of 3.7. * ``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 * The :func:`.gifti.relatedFiles` function now supports files with
BIDS-style naming conventions. BIDS-style naming conventions.
* The :func:`.run.run` and :func:`.run.runfsl` functions now pass through any * The :func:`.run.run` and :func:`.run.runfsl` functions now pass through any
...@@ -54,6 +59,8 @@ Changed ...@@ -54,6 +59,8 @@ Changed
* The :func:`.fileOrText` decorator has been updated to work with input * The :func:`.fileOrText` decorator has been updated to work with input
values - file paths must be passed in as ``pathlib.Path`` objects, so they values - file paths must be passed in as ``pathlib.Path`` objects, so they
can be differentiated from input values. 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 Fixed
...@@ -69,6 +76,24 @@ Fixed ...@@ -69,6 +76,24 @@ Fixed
a single set of coordinates. 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) 2.8.4 (Monday 2nd March 2020)
----------------------------- -----------------------------
......
...@@ -58,7 +58,6 @@ import fsl.utils.image.resample as resample ...@@ -58,7 +58,6 @@ import fsl.utils.image.resample as resample
import fsl.transform.affine as affine import fsl.transform.affine as affine
import fsl.utils.notifier as notifier import fsl.utils.notifier as notifier
import fsl.utils.settings as fslsettings import fsl.utils.settings as fslsettings
import fsl.utils.deprecated as deprecated
log = logging.getLogger(__name__) log = logging.getLogger(__name__)
...@@ -1085,24 +1084,6 @@ class StatisticAtlas(Atlas): ...@@ -1085,24 +1084,6 @@ class StatisticAtlas(Atlas):
return avgvals 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): class ProbabilisticAtlas(StatisticAtlas):
"""A 4D atlas which contains one volume for each region. Each volume """A 4D atlas which contains one volume for each region. Each volume
contains probabiliy values for one region, between 0 and 100. contains probabiliy values for one region, between 0 and 100.
......
...@@ -52,7 +52,6 @@ import fsl.transform.affine as affine ...@@ -52,7 +52,6 @@ import fsl.transform.affine as affine
import fsl.utils.notifier as notifier import fsl.utils.notifier as notifier
import fsl.utils.memoize as memoize import fsl.utils.memoize as memoize
import fsl.utils.path as fslpath import fsl.utils.path as fslpath
import fsl.utils.deprecated as deprecated
import fsl.utils.bids as fslbids import fsl.utils.bids as fslbids
import fsl.data.constants as constants import fsl.data.constants as constants
import fsl.data.imagewrapper as imagewrapper import fsl.data.imagewrapper as imagewrapper
...@@ -993,7 +992,6 @@ class Image(Nifti): ...@@ -993,7 +992,6 @@ class Image(Nifti):
xform=None, xform=None,
loadData=True, loadData=True,
calcRange=True, calcRange=True,
indexed=False,
threaded=False, threaded=False,
dataSource=None, dataSource=None,
loadMeta=False, loadMeta=False,
...@@ -1002,7 +1000,7 @@ class Image(Nifti): ...@@ -1002,7 +1000,7 @@ class Image(Nifti):
:arg image: A string containing the name of an image file to load, :arg image: A string containing the name of an image file to load,
or a :mod:`numpy` array, or a :mod:`nibabel` image or a :mod:`numpy` array, or a :mod:`nibabel` image
object. object, or an ``Image``object.
:arg name: A name for the image. :arg name: A name for the image.
...@@ -1035,9 +1033,6 @@ class Image(Nifti): ...@@ -1035,9 +1033,6 @@ class Image(Nifti):
incrementally updated as more data is read from memory incrementally updated as more data is read from memory
or disk. 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 :arg threaded: If ``True``, the :class:`.ImageWrapper` will use a
separate thread for data range calculation. Defaults separate thread for data range calculation. Defaults
to ``False``. Ignored if ``loadData`` is ``True``. to ``False``. Ignored if ``loadData`` is ``True``.
...@@ -1059,12 +1054,6 @@ class Image(Nifti): ...@@ -1059,12 +1054,6 @@ class Image(Nifti):
nibImage = None nibImage = None
saved = False saved = False
if indexed is not False:
warnings.warn('The indexed argument is deprecated '
'and has no effect',
category=DeprecationWarning,
stacklevel=2)
if loadData: if loadData:
threaded = False threaded = False
...@@ -1463,14 +1452,6 @@ class Image(Nifti): ...@@ -1463,14 +1452,6 @@ class Image(Nifti):
self.notify(topic='saveState') 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): def __getitem__(self, sliceobj):
"""Access the image data with the specified ``sliceobj``. """Access the image data with the specified ``sliceobj``.
...@@ -1661,9 +1642,3 @@ def defaultExt(): ...@@ -1661,9 +1642,3 @@ def defaultExt():
outputType = os.environ.get('FSLOUTPUTTYPE', 'NIFTI_GZ') outputType = os.environ.get('FSLOUTPUTTYPE', 'NIFTI_GZ')
return options.get(outputType, '.nii.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)
...@@ -31,8 +31,7 @@ from typing import Dict, List, Tuple ...@@ -31,8 +31,7 @@ from typing import Dict, List, Tuple
import numpy as np import numpy as np
from fsl.utils.deprecated import deprecated from . import FileTree
from . import FileTree
log = logging.getLogger(__name__) log = logging.getLogger(__name__)
...@@ -207,15 +206,6 @@ class FileTreeQuery(object): ...@@ -207,15 +206,6 @@ class FileTreeQuery(object):
return list(self.__templatevars.keys()) 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): def query(self, template, asarray=False, **variables):
"""Search for files of the given ``template``, which match """Search for files of the given ``template``, which match
the specified ``variables``. All hits are returned for variables the specified ``variables``. All hits are returned for variables
...@@ -292,12 +282,6 @@ class Match(object): ...@@ -292,12 +282,6 @@ class Match(object):
return self.__filename return self.__filename
@property
@deprecated('2.6.0', '3.0.0', 'Use template instead')
def short_name(self):
return self.template
@property @property
def template(self): def template(self):
return self.__template return self.__template
......
...@@ -85,8 +85,6 @@ from collections import abc ...@@ -85,8 +85,6 @@ from collections import abc
try: import queue try: import queue
except ImportError: import Queue as queue except ImportError: import Queue as queue
from fsl.utils.deprecated import deprecated
log = logging.getLogger(__name__) log = logging.getLogger(__name__)
...@@ -597,36 +595,6 @@ def idleWhen(*args, **kwargs): ...@@ -597,36 +595,6 @@ def idleWhen(*args, **kwargs):
idleLoop.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): def block(secs, delta=0.01, until=None):
"""Blocks for the specified number of seconds, yielding to the main ``wx`` """Blocks for the specified number of seconds, yielding to the main ``wx``
loop. loop.
......
...@@ -18,7 +18,6 @@ import numpy as np ...@@ -18,7 +18,6 @@ import numpy as np
import scipy.ndimage as ndimage import scipy.ndimage as ndimage
import fsl.transform.affine as affine import fsl.transform.affine as affine
import fsl.utils.deprecated as deprecated
def resampleToPixdims(image, newPixdims, **kwargs): def resampleToPixdims(image, newPixdims, **kwargs):
...@@ -282,13 +281,3 @@ def applySmoothing(data, matrix, newShape): ...@@ -282,13 +281,3 @@ def applySmoothing(data, matrix, newShape):
sigma[ratio >= 1.1] *= 0.425 sigma[ratio >= 1.1] *= 0.425
return ndimage.gaussian_filter(data, sigma) 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, :]
...@@ -180,13 +180,17 @@ def run(*args, **kwargs): ...@@ -180,13 +180,17 @@ def run(*args, **kwargs):
returnStderr = kwargs.pop('stderr', False) returnStderr = kwargs.pop('stderr', False)
returnExitcode = kwargs.pop('exitcode', False) returnExitcode = kwargs.pop('exitcode', False)
submit = kwargs.pop('submit', {}) submit = kwargs.pop('submit', {})
log = kwargs.pop('log', {}) log = kwargs.pop('log', None)
tee = log .get('tee', False)
logStdout = log .get('stdout', None)
logStderr = log .get('stderr', None)
logCmd = log .get('cmd', None)
args = prepareArgs(args) 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): if not bool(submit):
submit = None submit = None
......
#!/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')
...@@ -47,7 +47,7 @@ import re ...@@ -47,7 +47,7 @@ import re
import string import string
__version__ = '2.9.0.dev0' __version__ = '3.1.0.dev0'
"""Current version number, as a string. """ """Current version number, as a string. """
......
...@@ -37,12 +37,15 @@ instead. Aliases may also be used to provide a more readable interface (e.g. ...@@ -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``). the :func:`.bet` function uses ``mask`` instead of ``m``).
One exception to the above is :class:`.fslmaths`, which provides a more Two exceptions to the above are :class:`.fslmaths` and :class:`.fslstats`,
object-oriented interface:: 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') 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 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 will for the most part accept either in-memory ``nibabel`` images/Numpy arrays
...@@ -95,6 +98,7 @@ from .fnirt import (fnirt, # noqa ...@@ -95,6 +98,7 @@ from .fnirt import (fnirt, # noqa
invwarp, invwarp,
convertwarp) convertwarp)
from .fslmaths import (fslmaths,) # noqa from .fslmaths import (fslmaths,) # noqa
from .fslstats import (fslstats,) # noqa
from .fugue import (fugue, # noqa from .fugue import (fugue, # noqa
prelude, prelude,
sigloss) sigloss)
......
#!/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