CHANGELOG.rst



To find the state of this project's repository at the time of any of these versions, check out the tags.


This document contains the fslpy release history in reverse chronological
order.

3.6.0 (Under development)

Changed

The fslpy API ocumentation is now hosted at
https://open.win.ox.ac.uk/fsl/fslpy

The :mod:`fsl` and :mod:`fsl.scripts` packages have been changed from being
pkgutil-style
namespace packages to now being native
namespace packages.
The :class:`.TaskThread` now allows an error handler function to be
specified, which is run on the :mod:`.idle` loop.
The :func:`.bids.loadMetadata` function no long resolves sym-links when
determining whether a file is contained within a BIDS data set.


Deprecated

Deprecated a number of GUI-specific properties in the
:mod:`fsl.utils.platform` module, including frozen, haveGui,
canHaveGui, inSSHSession, inVNCSession, wxPlatform,
wxFlavour, glVersion, glRenderer, and glIsSoftwareRenderer.
Equivalent functions are being added to the fsleyes-widgets library.
The :mod:`fsl.utils.filetree` package has been deprecated, and will be
removed in a future version of fslpy - it is now published as a separate
library on [PyPI](https://pypi.org/project/file-tree/).


Fixed

Fixed an edge-case in the :mod:`.gifti` module, where a surface with a
single triangle was being loaded incorrectly.


3.5.3 (Tuesday 9th February 2021)
Fixed

Fixed a bug in :func:`.featanalysis.loadClusterResults` (!281).


3.5.2 (Friday 29th January 2021)
Fixed

Adjusted the :func:`.dicom.scanDir` function so that it will set a
default value for SeriesDescription if it is not present in the
dcm2niix json output (!279).
Fixed some issues with API documentation generation (!279).


3.5.1 (Thursday 21st January 2021)

Added

New :func:`.featanalysis.loadFsf` function, for loading arbitrary .fsf
files (!276).


Fixed

Adjustments to :mod:`.dicom` tests to work with different versions of
dcm2niix (!277).


3.5.0 (Wednesday 20th January 2021)

Added

New fsl_anat.tree, for use with the :mod:`.filetree` package (!264).
New :func:`.fsl_prepare_fieldmap` wrapper function (!265).
The :class:`.fslmaths` wrapper now supports the fslmaths -s option
via the :meth:`.fslmaths.smooth` method (!271).


Fixed

Windows/WSL-specific workaround to the :func:`fsl.utils.run.run` function to
avoid console windows from popping up, when used from a graphical program
(!272).


3.4.0 (Tuesday 20th October 2020)

Added

New :mod:`.tbss` wrapper functions for TBSS commands.


Changed

Calls to functions in the :mod:`.assertions` module are disabled when a
wrapper function is called with cmdonly=True.


3.3.3 (Wednesday 13th October 2020)
Changed

The :func:`.fileOrImage` (and related) decorators will not manipulate the
return value of a decorated function if an argument cmdonly=True is
passed. This is so that wrapper functions will directly return the command
that would be executed when cmdonly=True.


3.3.2 (Tuesday 12th October 2020)
Changed

Most :func:`.wrapper` functions now accept an argument called cmdonly
which, if True, will cause the generated command-line call to be
returned, instead of executed.


3.3.1 (Thursday 8th October 2020)

Changed

The :func:`.affine.decompose` and :func:`.affine.compose` functions now
have the ability to return/accept shear components.


Fixed

Fixed a bug in the :func:`.affine.decompose` function which was corrupting
the scale estimates when given an affine containing shears.


3.3.0 (Tuesday 22nd September 2020)

Added

New ported versions of various core FSL tools, including imrm, imln,
imtest, fsl_abspath, remove_ext, Text2Vest, and
Vest2Text.
New :func:`.gps` function, wrapping the FSL gps command.
New :func:`.vest.loadVestFile` and :func:`.vest.generateVest` functions.


Changed

Updates to the BIDS filetree specification.


Fixed

The :class:`.CoefficientField` class now works with alternate reference
images (i.e. a reference image with different dimensions to that which
was originally used when the non-linear transformation was calculated).


3.2.2 (Thursday 9th July 2020)
Changed

The :func:`.fslsub.func_to_cmd` function allows more fine-grained control
over whether the script file is removed after the job has finished running.


3.2.1 (Tuesday 23rd June 2020)
Changed

Minor updates to documentation.


3.2.0 (Thursday 11th June 2020)

Added

A new :func:`.fslsub.hold` function to wait on previously submitted jobs, to
be used in place of the wait function.


Removed

The :func:`.fslsub.wait` (and :func:`.run.wait`) function has been removed, as
repeated calls to qstat can adversely affect the cluster job submission
system.


3.1.0 (Thursday 21st May 2020)

Added

New :mod:`.cifti` module, providing classes and functions for working with
CIFTI data.
New :func:`.winpath` and :func:`wslpath` functions for working with paths
when using FSL in a Windows Subsystem for Linux (WSL) environment.
New :func:`.wslcmd` function for generating a path to a FSL command installed
in a WSL environment.
New :meth:`.Platform.fslwsl` attribute for detecting whether FSL is installed
in a WSL environment.
New :meth:`.Image.niftiDataType` property.
The :class:`.FileTree` class has been updated to allow creation of
deep copies via the new :meth:`.FileTree.copy` method.


Changed

:func:`.Image` objects created from numpy arrays will be NIFTI1 or
NIFTI2, depending on the value of the $FSLOUTPUTTYPE environment
variable.


Fixed

Updated the :func:`.fast` wrapper to support some single-character
command-line flags.


3.0.1 (Wednesday 15th April 2020)
Changed

The :func:`.isMelodicDir` function now accepts directories that do not end
with .ica, as long as all required files are present.
Added the dataclasses backport, so fslpy is now compatible with
Python 3.6 again.


3.0.0 (Sunday 29th March 2020)

Added

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.
The :func:`.nonlinear.applyDeformation` function now accepts a premat
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


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
additional keyword arguments to subprocess.Popen or, if submit=True,
to :func:`fslsub.submit`.
The :func:`.fslsub.submit` function now accepts an env option, allowing
environment variables to be specified.
The :func:`.run.runfsl` function now raises an error on attempts to
run a command which is not present in $FSLDIR/bin/ (e.g. ls).
The :mod:`.bids` module has been updated to support files with any
extension, not just those in the core BIDS specification (.nii,
.nii.gz, .json, .tsv).
The return value of a function decorated with :func:`.fileOrImage`,
:func:`.fileOrArray`, or :func:`.fileOrText` is now accessed via an attribute
called stdout, instead of output.
Output files of functions decorated with :func:`.fileOrImage`,
:func:`.fileOrArray`, or :func:`.fileOrText`, which have been loaded via the
:attr:`.LOAD` symbol, can now be accessed as attributes of the returned
results object, in addition to being accessed as dict items.
Wrapper functions decorated with the :func:`.fileOrImage`,
:func:`.fileOrArray`, or :func:`.fileOrText` decorators will now pass all
arguments and return values through unchanged if an argument called submit
is passed in, and is set to True (or any non-False
value). Furthermore, in such a scenario a :exc:`ValueError` will be raised if
any in-memory objects or LOAD symbols are passed.
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

Updated the :func:`.prepareArgs` function to use shlex.split when
preparing shell command arguments, instead of performing a naive whitespace
split.
Fixed some bugs in the :func:`.fslsub.info` and :func:`.fslinfo.wait`
functions.
Fixed the :func:`.DeformationField.transform` method so it works with
a single set of coordinates.
:class:`.Image` creation does not fail if loadMeta is set, and a
sidecar file containing invalid JSON is present.


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

Added a new partial_fill option to :meth:`.FileTree.read`, which
effectively eliminates any variables which only have one value. This was
added to accommodate some behavioural changes that were introduced in 2.8.2.


2.8.3 (Friday 28th February 2020)
Fixed

Fixed a bug in the :meth:`.Image.save` method.


2.8.2 (Thursday 27th February 2020)
Fixed

Fixed some subtle bugs in the :func:`.filetree.utils.get_all` function.


2.8.1 (Thursday 20th February 2020)
Fixed

Fixed a bug where an error would be raised on attempts to load an image file
without a BIDS-compatible name from a BIDS-like directory.


2.8.0 (Wednesday 29th January 2020)

Added

New :meth:`.Nifti.adjust` method, for creating a copy of a :class:`.Nifti`
header with adjusted shape, pixdims, and affine. This can be useful for
creating a resampling reference.
New :func:`.affine.rescale` function, for adjusting a scaling matrix.
New :func:`.mghimage.voxToSurfMat` function, for creating a
voxel-to-freesurfer affine transform from any image.


Changed

The :class:`.ImageWrapper` now maintains its own image data cache, rather
than depending on nibabel.
Internal changes to avoid using the deprecated
nibabel.dataobj_images.DataobjImage.get_data method.


Fixed

Improved the algorithm used by the :func:`.mesh.needsFixing` function.
The :meth:`.fslmaths.run` method now accepts :attr:`.wrappers.LOAD` as an
output specification.
Fixed a bug in the :class:`.Mesh` class to prevent indices from being loaded
as floating point type.
Fixed a bug in the :func:`.resample` function.
Fixed a bug in the :class:`.MGHImage` class, which was causing pixdims to
be overridden by scales derived from the affine.


Deprecated

:func:`.calculateMatrix` - its functionality has been moved to the
:func:`.affine.rescale` function.


2.7.0 (Wednesday 6th November 2019)

Added

New until option to the :func:`.idle.block` function.
New :meth:`.Idle.neverQueue` setting, which can be used to force all
tasks passed to :func:`.idle.idle` to be executed synchronously.
New :meth:`.IdleLoop.synchronous` context manager, to temporarily change the
value of :meth:`.IdleLoop.neverQueue`.
New :mod:`.bids` module, containing a few simple functions for working with
BIDS datasets.
New :func:`.image.loadMetadata` function, and loadMeta option to the
:class:`.Image` class, to automatically find and load any sidecar JSON files
associated with an image file.


Changed

Internal reorganisation in the :mod:`.idle` module.


Fixed

Fixed incorrect usage of setuptools.find_packages, which was causing
unit tests to be installed.


Deprecated

:func:`.idle.inIdle` - replaced by :meth:`.IdleLoop.inIdle`.
:func:`.idle.cancelIdle` - replaced by :meth:`.IdleLoop.cancelIdle`.
:func:`.idle.idleReser` - replaced by :meth:`.IdleLoop.idleReset`.
:func:`.idle.getIdleTimeout` - replaced by :meth:`.IdleLoop.callRate`.
:func:`.idle.setIdleTimeout` - replaced by :meth:`.IdleLoop.callRate`.


2.6.2 (Monday 7th October 2019)
Changed

Added a debugging hook in the :mod:`.idle` module.
The :func:`.fslsub.submit` function is now more flexible in the way it
accepts the command and input arguments.
The :func:`.run.prepareArgs` function has been renamed (from
_prepareArgs).


2.6.1 (Thursday 19th September 2019)
Changed


fslpy is no longer tested against Python 3.5, and is now tested against
Python 3.6, 3.7, and 3.8.


2.6.0 (Tuesday 10th September 2019)

Added

New :meth:`.Image.iscomplex` attribute.
Support for a new Statistic atlas type.


Changed

The :class:`.Cache` class has a new lru option, allowing it to be used
as a least-recently-used cache.
The :mod:`fsl.utils.filetree` module has been refactored to make it easier
for the :mod:`.query` module to work with file tree hierarchies.
The :meth:`.LabelAtlas.get` method has a new binary flag, allowing
either a binary mask, or a mask with the original label value, to be
returned.
The :mod:`.dicom` module has been updated to work with the latest version of
dcm2niix.


Deprecated

:meth:`.ProbabilisticAtlas.proportions`,
:meth:`.ProbabilisticAtlas.maskProportions`, and
:meth:`.ProbabilisticAtlas.labelProportions` have been deprecated in favour
of :meth:`.StatisticAtlas.values`, :meth:`.StatisticAtlas.maskValues`, and
:meth:`.StatisticAtlas.labelValues`


2.5.0 (Tuesday 6th August 2019)

Added

New :meth:`.Image.getAffine` method, for retrieving an affine between any of
the voxel, FSL, or world coordinate systems.
New :mod:`fsl.transforms` package, which contains classes and functions for
working with linear and non-linear FLIRT and FNIRT transformations.
New static methods :meth:`.Nifti.determineShape`,
:meth:`.Nifti.determineAffine`, :meth:`.Nifti.generateAffines`, and
:meth:`.Nifti.identifyAffine`.
New prototype :mod:`fsl.transforms.x5`  module, for reading/writing linear
and non-linear X5 files (preliminary release, subject to change).
New prototype :mod:`.fsl_convert_x5` :mod:`.fsl_apply_x5` programs, for
working with X5 transformations (preliminary release, subject to change).


Changed

The :mod:`.vest.looksLikeVestLutFile` function has been made slightly more
lenient.

h5py has been added to the fslpy dependencies.


Deprecated

The :mod:`fsl.utils.transform` module has been deprecated; its functions can
now be found in the :mod:`fsl.transforms.affine` and
:mod:`fsl.transform.flirt` modules.


2.4.0 (Wednesday July 24th 2019)

Added

New :mod:`.image.roi` module, for extracting an ROI of an image, or expanding
its field-of-view.


Changed

The :mod:`.resample_image` script has been updated to support resampling of
images with more than 3 dimensions.


2.3.1 (Friday July 5th 2019)
Fixed

The :class:`.Bitmap` class now supports greyscale images and palette images.


2.3.0 (Tuesday June 25th 2019)

Added

New :class:`.Bitmap` class, for loading bitmap images. The
:meth:`.Bitmap.asImage` method can be used to convert a Bitmap into
an :class:`.Image`.
The :class:`.Image` class now has support for the RGB24 and RGBA32
NIfTI data types.
New :attr:`.Image.nvals` property, for use with RGB24/RGBA32
images.
New :meth:`.LabelAtlas.get` and :meth:`ProbabilisticAtlas.get` methods,
which return an :class:`.Image` for a specific region.
The :meth:`.AtlasDescription.find` method also now a name parameter,
allowing labels to be looked up by name.
New :meth:`.FileTree.defines` and :meth:`.FileTree.on_disk` methods, to
replace the :func:`.FileTree.exists` method.


Fixed

The :func:`.makeWriteable` function will always create a copy of an
array if its base is a bytes object.
Fixed a bug in the :meth:`.GitfitMesh.loadVertices` method.
Fixed a bug in the :meth:`.Mesh.addVertices` method where the wrong face
normals could be used for newly added vertex sets.


2.2.0 (Wednesday May 8th 2019)

Added

New :mod:`.resample_image` script.
New :mod:`.resample` module (replacing the :func:`.Image.resample` method),
containing functions to resample an :class:`.Image`.
New :func:`.resample.resampleToPixdim` and
:func:`.resample.resampleToReference` functions, convenience wrappers around
:func:`.resample.resample`.
New :func:`.idle.block` function.


Changed

The :func:`.resample` function (formerly :meth:`.Image.resample`) now
accepts origin and matrix parameters, which can be used to adjust
the alignment of the voxel grids of the input and output images.
The :func:`.transform.decompose` function now accepts both (3, 3)
and (4, 4) matrices.


Fixed

Minor fixes to some :mod:`.filetree.filetree` tree definitions.


Deprecated

The :meth:`.Image.resample` method has been deprecated in favour of the
:func:`.resample.resample` function.


2.1.0 (Saturday April 13th 2019)

Added

New tensor conversion routines in the :mod:`.dtifit` module (Michiel
Cottaar).
New :func:`.makeWriteable` function which ensures that a numpy.array is
writeable, and creates a copy if necessary