fslpy release history

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

3.4.0 (Tuesday 20th October 2020)

Added

  • New tbss wrapper functions for TBSS commands.

Changed

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

3.3.3 (Wednesday 13th October 2020)

Changed

  • The 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 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

Fixed

  • Fixed a bug in the 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 gps() function, wrapping the FSL gps command.

  • New vest.loadVestFile() and vest.generateVest() functions.

Changed

  • Updates to the BIDS filetree specification.

Fixed

  • The 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 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 fslsub.hold() function to wait on previously submitted jobs, to be used in place of the wait function.

Removed

  • The fslsub.wait() (and 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 cifti module, providing classes and functions for working with CIFTI data.

  • New winpath() and wslpath() functions for working with paths when using FSL in a Windows Subsystem for Linux (WSL) environment.

  • New wslcmd() function for generating a path to a FSL command installed in a WSL environment.

  • New Platform.fslwsl() attribute for detecting whether FSL is installed in a WSL environment.

  • New Image.niftiDataType() property.

  • The FileTree class has been updated to allow creation of deep copies via the new FileTree.copy() method.

Changed

  • Image() objects created from numpy arrays will be NIFTI1 or NIFTI2, depending on the value of the $FSLOUTPUTTYPE environment variable.

Fixed

  • Updated the fast() wrapper to support some single-character command-line flags.

3.0.1 (Wednesday 15th April 2020)

Changed

  • The 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

Changed

  • fslpy now requires a minimum Python version of 3.7.

  • The default value for the partial_fill option to FileTree.read() has been changed to False. Accordingly, the FileTreeQuery calls the FileTree.partial_fill() method on the FileTree it is given.

  • The gifti.relatedFiles() function now supports files with BIDS-style naming conventions.

  • The run.run() and run.runfsl() functions now pass through any additional keyword arguments to subprocess.Popen or, if submit=True, to fslsub.submit().

  • The fslsub.submit() function now accepts an env option, allowing environment variables to be specified.

  • The run.runfsl() function now raises an error on attempts to run a command which is not present in $FSLDIR/bin/ (e.g. ls).

  • The 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 fileOrImage(), fileOrArray(), or fileOrText() is now accessed via an attribute called stdout, instead of output.

  • Output files of functions decorated with fileOrImage(), fileOrArray(), or fileOrText(), which have been loaded via the 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 fileOrImage(), fileOrArray(), or 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 ValueError will be raised if any in-memory objects or LOAD symbols are passed.

  • The 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 Image objects returned by fsl.wrappers functions are now named according to the wrapper function argument name.

Fixed

  • Updated the prepareArgs() function to use shlex.split when preparing shell command arguments, instead of performing a naive whitespace split.

  • Fixed some bugs in the fslsub.info() and fslinfo.wait() functions.

  • Fixed the DeformationField.transform() method so it works with a single set of coordinates.

  • 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 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 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

2.8.2 (Thursday 27th February 2020)

Fixed

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 Nifti.adjust() method, for creating a copy of a Nifti header with adjusted shape, pixdims, and affine. This can be useful for creating a resampling reference.

  • New affine.rescale() function, for adjusting a scaling matrix.

  • New mghimage.voxToSurfMat() function, for creating a voxel-to-freesurfer affine transform from any image.

Changed

  • The 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 mesh.needsFixing() function.

  • The fslmaths.run() method now accepts wrappers.LOAD as an output specification.

  • Fixed a bug in the Mesh class to prevent indices from being loaded as floating point type.

  • Fixed a bug in the resample() function.

  • Fixed a bug in the MGHImage class, which was causing pixdims to be overridden by scales derived from the affine.

Deprecated

  • calculateMatrix() - its functionality has been moved to the affine.rescale() function.

2.7.0 (Wednesday 6th November 2019)

Added

  • New until option to the idle.block() function.

  • New Idle.neverQueue() setting, which can be used to force all tasks passed to idle.idle() to be executed synchronously.

  • New IdleLoop.synchronous() context manager, to temporarily change the value of IdleLoop.neverQueue().

  • New bids module, containing a few simple functions for working with BIDS datasets.

  • New image.loadMetadata() function, and loadMeta option to the Image class, to automatically find and load any sidecar JSON files associated with an image file.

Changed

  • Internal reorganisation in the idle module.

Fixed

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

Deprecated

2.6.2 (Monday 7th October 2019)

Changed

  • Added a debugging hook in the idle module.

  • The fslsub.submit() function is now more flexible in the way it accepts the command and input arguments.

  • The 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

Changed

  • The Cache class has a new lru option, allowing it to be used as a least-recently-used cache.

  • The fsl.utils.filetree module has been refactored to make it easier for the query module to work with file tree hierarchies.

  • The 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 dicom module has been updated to work with the latest version of dcm2niix.

Deprecated

2.5.0 (Tuesday 6th August 2019)

Added

  • New Image.getAffine() method, for retrieving an affine between any of the voxel, FSL, or world coordinate systems.

  • New fsl.transforms package, which contains classes and functions for working with linear and non-linear FLIRT and FNIRT transformations.

  • New static methods Nifti.determineShape(), Nifti.determineAffine(), Nifti.generateAffines(), and Nifti.identifyAffine().

  • New prototype fsl.transforms.x5 module, for reading/writing linear and non-linear X5 files (preliminary release, subject to change).

  • New prototype fsl_convert_x5 fsl_apply_x5 programs, for working with X5 transformations (preliminary release, subject to change).

Changed

  • The vest.looksLikeVestLutFile function has been made slightly more lenient.

  • h5py has been added to the fslpy dependencies.

Deprecated

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

2.4.0 (Wednesday July 24th 2019)

Added

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

Changed

  • The 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 Bitmap class now supports greyscale images and palette images.

2.3.0 (Tuesday June 25th 2019)

Added

Fixed

  • The makeWriteable() function will always create a copy of an array if its base is a bytes object.

  • Fixed a bug in the GitfitMesh.loadVertices() method.

  • Fixed a bug in the Mesh.addVertices() method where the wrong face normals could be used for newly added vertex sets.

2.2.0 (Wednesday May 8th 2019)

Added

Changed

  • The resample() function (formerly 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 transform.decompose() function now accepts both (3, 3) and (4, 4) matrices.

Fixed

Deprecated

  • The Image.resample() method has been deprecated in favour of the resample.resample() function.

2.1.0 (Saturday April 13th 2019)

Added

  • New tensor conversion routines in the dtifit module (Michiel Cottaar).

  • New makeWriteable() function which ensures that a numpy.array is writeable, and creates a copy if necessary

Changed

  • The GiftiMesh class no longer creates copies of the mesh vertex/index arrays. This means that, these arrays will be flagged as read-only.

  • The Mesh class handles vertex data sets requiring different triangle unwinding orders, at the cost of potentially having to store two copies of the mesh indices.

Fixed

  • The FeatDesign class now handles “compressed” voxelwise EV files, such as those generated by PNM.

2.0.1 (Monday April 1st 2019)

Fixed

2.0.0 (Friday March 20th 2019)

Added

  • New fsl.utils.filetree package for defining and working with file/directory templates (Michiel Cottaar).

  • Simple built-in deprecated decorator.

  • New fsl.data.utils module, which currently contains one function guessType(), which guesses the data type of a file/directory path.

  • New commonBase() function for finding the common prefix of a set of file/directory paths.

Changed

  • Removed support for Python 2.7 and 3.4.

  • Minimum required version of nibabel is now 2.3.

  • The Image class now fully delegates to nibabel for managing file handles.

  • The GiftiMesh class can now load surface files which contain vertex data, and will accept surface files which end in .gii, rather than requiring files which end in .surf.gii.

  • The name property of Mesh instances can now be updated.

Removed

  • Many deprecated items removed.

Deprecated

  • Deprecated the loadIndexedImageFile() function, and the indexed flag to the Image constructor.

1.13.3 (Friday February 8th 2019)

Fixed

  • Fixed an issue with the dicom.loadSeries() using memory-mapping for image files that would subsequently be deleted.

  • Fixed an issue in the GiftiMesh class, where numpy/nibabel was returning read-only index arrays.

1.13.2 (Friday November 30th 2018)

Changed

  • The Image.resample() method now supports images with more than three dimensions.

  • The fsl.utils.fslsub.submit() now returns the job-id as a string rather than a one-element tuple. It now also accepts a nested sequence of job ids rather than just a flat sequence. This will also changes the output from the function wrappers in fsl.wrappers if submitted.

Fixed

1.13.1 (Friday November 23rd 2018)

Fixed

  • Added a missing image attribute in the VoxelwiseConfoundEV class.

  • Make sure that FEAT Cluster objects (created by the loadClusterResults() function) contain p and logp attributes, even when cluster thresholding was not used.

1.13.0 (Thursday 22nd November 2018)

Added

Changed

  • Various minor changes and enhancements to the FSL function wrappers interfaces (Martin Craig).

Fixed

  • The immv and imcp scripts now accept incorrect file extensions on input arguments.

1.12.0 (Sunday October 21st 2018)

Changed

  • The extract_noise script has been renamed to fsl_ents.

  • Increased the minimum required version of dcm2niix in the fsl.data.dicom module.

Deprecated

  • The extract_noise script.

1.11.1 (Friday September 14th 2018

Fixed

  • Fixed a Python 2 incompatibility in the settings module.

1.11.0 (Thursday September 13th 2018)

Added

  • A couple of new convenience functions to the settings module.

Changed

  • Development (test and documentation dependencies) are no longer listed in setup.py - they now need to be installed manually.

  • Removed conda build infrastructure.

1.10.3 (Sunday September 9th 2018)

Added

1.10.2 (Friday September 7th 2018)

Fixed

  • The Image.save() method was not handling memory-mapped images correctly.

1.10.1 (Friday August 3rd 2018)

Changed

  • Minor adjustmenets to improve Windows compatibility.

Fixed

  • The FEATImage.getCOPE method was returning PE images.

1.10.0 (Wednesday July 18th 2018)

Added

  • A new script, extract_noise, which can be used to extract ICA component time courses from a MELODIC ICA analysis.

  • New path.allFiles() function which returns all files underneath a directory.

  • The fileOrImage() and fileOrArray() decorators now support loading of files which are specified with an output basename.

  • New fast wrapper function for the FSL FAST tool.

Changed

  • When using the run.run() function, the command output/error streams are now forwarded immediately.

  • Removed dependency on pytest-runner.

1.9.0 (Monday June 4th 2018)

Added

  • New Image.data() property method, for easy access to image data as a numpy array.

  • New log option to the run.run() function, allowing more fine-grained control over sub-process output streams.

  • New Platform.fsldevdir() property, allowing the $FSLDEVDIR environment variable to be queried/changed.

Changed

  • Image.ndims() has been renamed to Image.ndim(), to align more closely with numpy naming conventions.

  • The err and ret parameters to the run.run() function have been renamed to stderr and exitcode respectively.

  • The runfsl() function will give priority to the $FSLDEVDIR environment variable if it is set.

Deprecated

  • Image.ndims().

  • The err and ret parameters to run.run().

1.8.1 (Friday May 11th 2018)

Changed

  • The fileOrImage() decorator function now accepts Image objects as well as nibabel image objects.

1.8.0 (Thursday May 3rd 2018)

Added

Changed

  • The tempdir() function has an option to not change to the newly created directory.

Deprecated

1.7.2 (Monday March 19th 2018)

Added

  • Added the MGHImage.voxToSurfMat() and related properties, giving access to the voxel-to-surface affine for an MGH image.

1.7.1 (Monday March 12th 2018)

Changed

Fixed

  • Removed deprecated use of imagewrapper.canonicalShape().

1.7.0 (Tuesday March 6th 2018)

Added

  • The fsl.utils.assertions module contains a range of functions which can be used to assert that some condition is met.

  • The fsl.utils.ensure module contains a range of functions (currently just one) which can be used to ensure that some condiution is met.

Changed

  • The settings module now saves its files in a format that is compatible with Python 2 and 3.

  • The tempdir() function now accepts a root argument, which specifies the location in which the temporary directory should be created.

  • An image’s data source can now be set via Image.__init__().

  • MGHImage() objects now have a MGHImage.save() method.

  • Adjustments to the conda package build and deployment process.

  • The ImageWrapper.canonicalShape() function has been moved to the data.image class.

  • The ImageWrapper.naninfrange() function has been moved into its own naninfrange module.

Fixed

Deprecated

  • ImageWrapper.canonicalShape() (moved to the data.image module)

  • ImageWrapper.naninfrange() function (moved to the naninfrange module)

1.6.8 (Monday February 12th 2018)

  • The atlasq, immv, imcp and imglob scripts suppress some warnings.

1.6.7 (Friday February 9th 2018)

  • More further adjustments to the conda package build.

  • Adjustments to pypi source distribution - the requirements-extra.txt file was not being included.

1.6.6 (Thursday February 8th 2018)

  • Further adjustments to the conda package build.

1.6.5 (Tuesday February 6th 2018)

  • Adjustments to the conda package build.

1.6.4 (Monday February 5th 2018)

  • The platform module emits a warning if it cannot import wx.

1.6.3 (Friday February 2nd 2018)

  • Minor enhancements to the WeakFunctionRef class.

  • Some bugfixes to the fsl.utils.imcp module, with respect to handling relative path names, moving file groups (e.g. .img/.hdr pairs), and non-existent directories.

1.6.2 (Tuesday January 30th 2018)

  • Updates to the conda installation process.

  • A new script is installed when fslpy is installed via pip or conda - atlasquery, which emulates the FSL atlasquery tool.

1.6.1 (Monday January 29th 2018)

  • Removed lxml as a dependency - this was necessary in older versions of trimesh.

1.6.0 (Friday January 26th 2018)

  • The new Mesh class is now the base class for all mesh types. It has been written to allow multiple sets of vertices to be associated with a mesh object (to support e.g. white matter, inflated, spherical models for a GIFTI/freeusrfer mesh).

  • The new VTKMesh class must now be used for loading VTK model files, instead of the old TriangleMesh class.

  • The new Mesh class uses the trimesh library (https://github.com/mikedh/trimesh) to perform various geometrical operations, accessible via new Mesh.rayIntersection(), Mesh.planeIntersection(), Mesh.nearestVertex() methods.

  • The Nifti and Mesh classes have new methods allowing arbitrary metadata to be stored with the image, as key-value pairs. These are provided by a new mixin class, Meta.

  • Freesurer surface files and vertex data can now be loaded via the FreesurferMesh class, in the new freesurfer module.

  • Freesurfer mgz / mgh image files can now be loaded via the new mghimage module. Internally, these image files are converted to NIFTI - the MGHImage class derives from the Image class.

  • Meta-data access methods on the DicomImage class have been deprecated, as their functionality is provided by the new Meta mixin.

  • The TriangleMesh class has been deprecated in favour of the new Mesh class.

  • Optional dependencies wxpython, indexed_gzip, trimesh, and rtree are now listed separately, so fslpy can be used without them (although relevant functionality will be disabled if they are not present).

1.5.4 (Wednesday January 10th 2018)

  • Actually included the fix that was supposed to be in version 1.5.3.

1.5.3 (Tuesday January 9th 2018)

1.5.2 (Tuesday January 2nd 2018)

  • Fixed issue with MANIFEST.in file.

1.5.1 (Thursday December 14th 2017)

1.5.0 (Wednesday December 13th 2017)

  • New module dicom, which provides a thin wrapper on top of Chris Rorden’s dcm2niix.

  • New module tempdir, which has a convenience function for creating temporary directories.

  • Fixed small issue in Image.dtype() - making sure that it access image data via the ImageWrapper, rather than via the Nifti1Image object.

1.4.2 (Tuesday December 5th 2017)

1.4.1 (Thursday November 9th 2017)

  • Fixed bug in setup.py.

1.4.0 (Thursday November 9th 2017)

  • The uniquePrefix() function now raises a PathError instead of a ValueError, when an invalid path is provided.

  • The fsl.utils.async module is now deprecated, as async will become a reserved word in Python 3.7. It has been renamed to fsl.utils.idle, with no other API changes.

  • For image file pairs, the hdr extension now takes precedence over the img extension, when using the fsl.data.image.addExt() (and related) functions.

  • The fsl.utils.path.addExt() function accepts a new parameter, unambiguous which causes it to allow an ambiguous prefix, and return all matching paths.

  • New atlasq application, intended to replace the FSL atlasquery tool.

  • New imglob application, intended to replace the FSL imglob tool.

  • The Image.resample() method explicitly raises a ValueError if incompatible shapes are provided.

1.3.1 (Wednesday October 25th 2017)

1.3.0 (Wednesday October 25th 2017)

  • Atlas classes can now pass kwargs through to the Image constructor.

  • LabelAtlas image values no longer need to match the index of the label into the AtlasDescription labels list. This means that label atlas XML files may contain non-sequential label values.

  • Cache now implements __getitem__ and __setitem__

  • The image.read_segments() function (monkey-patched into nibabel) is deprecated, as it is no longer necessary as of nibabel 2.2.0.

  • platform.isWidgetAlive() is deprecated in favour of an equivalent function in the fsleyes-widgets library.

  • scipy is now explicitly listed as a requirement (this should have been done in 1.2.1).

1.2.2 (Saturday October 21st 2017)

  • The image.read_segments() function is only monkey-patched into nibabel 2.1.0, as it breaks when used with 2.2.0.

1.2.1 (Saturday October 7th 2017)

  • If an Image is passed an existing nibabel header object, it creates a copy, rather than using the original.

  • New Image.resample() method, which resamples the image data to a different resolution.

  • New LabelAtlas.coordLabel(), LabelAtlas.maskLabel(), ProbabilisticAtlas.coordProportions() and ProbabilisticAtlas.maskProportions() methods. The coord methods perform coordinate queries in voxel or world coordinates, and the mask methods perform mask-based queries.

1.2.0 (Thursday September 21st 2017)

  • fsl.data.image.Nifti.voxelsToScaledVoxels() method deprecated in favour of new Nifti.voxToScaledVoxMat() and Nifti.scaledVoxToVoxMat() properties.

1.1.0 (Monday September 11th 2017)

1.0.5 (Thursday August 10th 2017)

  • New functions and further adjustments in fsl.utils.transform module:

  • transform.rotMatToAffine() converts a (3, 3) rotation matrix into a (4, 4) affine.

  • transform.transformNormal() applies an affine transform to one or more vectors.

  • transform.veclength() calculates the length of a vector

  • transform.normalise() normalises a vector

  • transform.scaleOffsetXform() adjusted to have more flexibility with respect to inputs.

  • transform.decompose() can return rotations either as three axis-angles, or as a rotation matrix

  • Updates to fsl.data.mesh.TriangleMesh - vertices and indices are now property attributes. New lazily generated normals and vnormals properties (face and vertex normals respectively). Option to __init__ to fix the face winding order of a mesh.

  • fsl.utils.memoize.memoize() decorator made into a class rather than a function. The new Memoize class has an invalidate method, which clears the cache.

1.0.4 (Friday July 14th 2017)

  • Python 2/3 compatibility fix to fsl.utils.callfsl.

  • Fix to fsl.utils.transform.scaleOffsetXform() - accepts inputs that are not lists.

  • fsl.utils.transform.compose() accepts either a sequence of three axis angles, or a (3, 3) rotation matrix.

1.0.3 (Sunday June 11th 2017)

  • Fix to fsl.utils.async which was breaking environments where multiple wx.App instances were being created.

1.0.2 (Thursday June 8th 2017)

1.0.1 (Sunday 4th June 2017)

1.0.0 (Saturday May 27th 2017)

  • Removed many GUI-related modules - they have been moved to the fsleyes-widgets project. The following modules have been removed: - fsl.utils.colourbarbitmap - fsl.utils.dialog - fsl.utils.imagepanel - fsl.utils.layout - fsl.utils.platform - fsl.utils.runwindow - fsl.utils.status - fsl.utils.textbitmap - fsl.utils.typedict - fsl.utils.webpage

  • fsl.utils.settings module rewritten. It no longer uses wx, but instead stores plain-text and pickle files in the user’s home directory.

  • Software GL renderer test in fsl.utils.platform is more lenient

  • New AtlasLabel class

  • Image.__init__() allows arguments to be passed through to nibabel.load.

  • New Nifti.strval() method to handle escaped strings in NIFTI headers.

  • Python 2/3 compatibility fixes

0.11.0 (Thursday April 20th 2017)

  • First public release as part of FSL 5.0.10