fsl.wrappers.fslstats

This module provides the 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.

class fsl.wrappers.fslstats.fslstats(input, t=False, K=None, sep_volumes=False, index_mask=None)

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

This fslstats command:

fslstats image -r -p 95 -R

is equivalent to this function call:

fslstats('image').r.p(95).R.run()

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

fslstats('image.nii.gz').r.run()

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').k('mask.nii.gz').run()

The fslstats command can be executed via the 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 __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 = {'C': 'C', 'E': 'E', 'M': 'M', 'R': 'R', 'S': 'S', 'V': 'V', 'X': 'X', 'a': 'a', 'abs': 'a', 'c': 'c', 'cog_mm': 'c', 'cog_vox': 'C', 'e': 'e', 'm': 'm', 'max_vox': 'x', 'mean': 'm', 'mean_entropy': 'e', 'mean_entropy_nz': 'E', 'mean_nz': 'M', 'min_vox': 'X', 'minmax': 'R', 'n': 'n', 'r': 'r', 'robust_minmax': 'r', 's': 's', 'smallest_roi': 'w', 'stddev': 's', 'stddev_nz': 'S', 'v': 'v', 'volume': 'v', 'volume_nz': 'V', 'w': 'w', 'x': 'x', '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 = {'H': 'H', 'P': 'P', 'd': 'd', 'diff': 'd', 'h': 'h', 'hist': 'h', 'hist_bounded': 'H', 'k': 'k', 'l': 'l', 'lower_threshold': 'l', 'mask': 'k', 'p': 'p', 'percentile': 'p', 'percentile_nz': 'P', 'u': 'u', 'upper_threshold': 'u'}

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

__init__(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 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.

Parameters:

• input – Input image - either a file name, or an Image object, or a nibabel.Nifti1Image object.

• t – Produce separate results for each 3D volume in the input image.

• K – Produce separate results for each sub-mask within the provided mask image.

• sep_volumes – Alias for t.

• index_mask – Alias for K.

__getattr__(name)

Intercepts attribute accesses and accumulates fslstats command-line flags accordingly.

__addFlag(flag, *args)

Used by __getattr__(). Add the given flag and any arguments to the accumulated list of command-line options.

__dict__ = mappingproxy({'__module__': 'fsl.wrappers.fslstats', '__doc__': "The ``fslstats`` class is a wrapper around the ``fslstats`` command-line\n    tool. It provides an object-oriented interface - options are specified by\n    chaining method calls and attribute accesses together.\n\n\n    .. warning:: This wrapper function will only work with FSL 6.0.2 or newer,\n                 due to bugs in ``fslstats`` output formatting that are\n                 present in older versions.\n\n\n    This ``fslstats`` command::\n\n        fslstats image -r -p 95 -R\n\n\n    is equivalent to this function call::\n\n        fslstats('image').r.p(95).R.run()\n\n\n    Any ``fslstats`` command-line option which does not require any arguments\n    (e.g. ``-r``) can be set by accessing an attribute on a ``fslstats``\n    object, e.g.::\n\n        fslstats('image.nii.gz').r.run()\n\n\n    ``fslstats`` command-line options which do require additional arguments\n    (e.g. ``-k``) can be set by calling a method on an ``fslstats`` object,\n    e.g.::\n\n        stats = fslstats('image.nii.gz').k('mask.nii.gz').run()\n\n\n    The ``fslstats`` command can be executed via the :meth:`run` method.\n    Normally, the results will be returned as a scalar floating point number,\n    or a ``numpy`` array. Pre-options will affect the structure of the return\n    value - see :meth:`__init__` for details.\n\n\n    Attribute and method calls can be chained together, so a complete\n    ``fslstats`` call can be performed in a single line, e.g.::\n\n        imgmin, imgmax = fslstats('image.nii.gz').k('mask.nii.gz').r.run()\n    ", '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', 'r': 'r', 'R': 'R', 'e': 'e', 'E': 'E', 'v': 'v', 'V': 'V', 'm': 'm', 'M': 'M', 's': 's', 'S': 'S', 'w': 'w', 'x': 'x', 'X': 'X', 'c': 'c', 'C': 'C', 'a': 'a', 'n': 'n'}, 'ARG_OPTIONS': {'lower_threshold': 'l', 'upper_threshold': 'u', 'percentile': 'p', 'percentile_nz': 'P', 'mask': 'k', 'diff': 'd', 'hist': 'h', 'hist_bounded': 'H', 'l': 'l', 'u': 'u', 'p': 'p', 'P': 'P', 'k': 'k', 'd': 'd', 'h': 'h', 'H': 'H'}, '__init__': <function fslstats.__init__>, '__getattr__': <function fslstats.__getattr__>, '_fslstats__addFlag': <function fslstats.__addFlag>, 'run': <function fslstats.run>, '_fslstats__run': <function fslstats.__run>, '__dict__': <attribute '__dict__' of 'fslstats' objects>, '__weakref__': <attribute '__weakref__' of 'fslstats' objects>, '__annotations__': {}})

__module__ = 'fsl.wrappers.fslstats'

__weakref__

list of weak references to the object (if defined)

run(raw=False, **kwargs)

Run the fslstats command-line tool. See __init__() for a description of the return value.

Parameters:

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.

All other arguments are ultimately passed through to the fsl.utils.run.run() function.

__run(*cmd)

Run the given fslstats command.