Skip to content

GitLab

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
Hide whitespace changes
Inline Side-by-side
CHANGELOG.rst
View file @ 0a972e0c
......@@ -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
View file @ 0a972e0c
......@@ -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
View file @ 0a972e0c
......@@ -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
View file @ 0a972e0c
......@@ -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
View file @ 0a972e0c
......@@ -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
View file @ 0a972e0c
......@@ -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
View file @ 0a972e0c
......@@ -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 deleted 100644 → 0
View file @ 85609e78
#!/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
View file @ 0a972e0c
......@@ -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
View file @ 0a972e0c
......@@ -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 0 → 100644
View file @ 0a972e0c
#!/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
self.__input = input
self.__options = []
# pre-options must be supplied
# before input image
if t: self.__options.append( '-t')
if K is not None: self.__options.extend(('-K', K))
self.__options.append(input)
def __getattr__(self, name):
"""Intercepts attribute accesses and accumulates ``fslstats`` command-line
flags accordingly.
"""
# options which take no args
# are called as attributes
if name in fslstats.OPTIONS:
flag = fslstats.OPTIONS[name]
args = False
# options which take args
# are called as methods
elif name in fslstats.ARG_OPTIONS:
flag = fslstats.ARG_OPTIONS[name]
args = True
else:
raise AttributeError(name)
addFlag = ft.partial(self.__addFlag, flag)
if args: return addFlag
else: return addFlag()
def __addFlag(self, flag, *args):
"""Used by :meth:`__getattr__`. Add the given flag and any arguments to
the accumulated list of command-line options.
"""
self.__options.extend(('-' + flag,) + args)
return self
def run(self, raw=False):
"""Run the ``fslstats`` command-line tool. See :meth:`__init__` for a
description of the return value.
:arg raw: Defaults to ``False``. If ``True``, the raw standard output
and error is returned, instead of a scalar/numpy array.
:returns: Result of ``fslstats`` as a scalar or ``numpy`` array.
"""
# The parsing logic below will not work
# with versions of fslstats prior to fsl
# 6.0.2, due to a quirk in the output
# formatting of older versions.
# The default behaviour of run/runfsl
# is to tee the command output streams
# to the calling process streams. We
# can disable this via log=None.
result = self.__run('fslstats', *self.__options, log=None)
if raw:
return result.stdout
result = np.genfromtxt(io.StringIO(result.stdout[0].strip()))
sepvols = '-t' in self.__options
lblmask = '-K' in self.__options
# One line of output for each volume and
# for each label (with volume the slowest
# changing). Reshape to 3D.
if sepvols and lblmask:
# We need know the number of volumes
# (or the number of labels) in order
# to know how to shape the results.
img = fslimage.Image(self.__input, loadData=False)
if img.ndim >= 4: nvols = img.shape[3]
else: nvols = 1
# reshape the result into
# (nvals, nvols, nlbls)
nlbls = int(len(result) / nvols)
result = result.reshape((nvols, nlbls, -1)).squeeze()
# Scalar - use numpy indexing weirdness
# to get our single value out.
elif result.size == 1:
result = result[()]
return result
@wutils.fileOrImage()
@wutils.fslwrapper
def __run(self, *cmd):
"""Run the given ``fslmaths`` command. """
return [str(c) for c in cmd]
fsl/wrappers/wrapperutils.py
View file @ 0a972e0c
......@@ -403,18 +403,18 @@ def namedPositionals(func, args):
LOAD = object()
"""Constant used by the :class:`_FileOrThing` class to indicate that an output
"""Constant used by the :class:`FileOrThing` class to indicate that an output
file should be loaded into memory and returned as a Python object.
"""
class _FileOrThing(object):
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.